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, and non-destructive. The description adds useful behavioral detail: it routes to 5,724 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and works across all tiers with one fast call. It does not fully disclose failure modes or response-shape edge cases, but the added context exceeds what annotations alone 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 it is front-loaded with the most important routing directive and organized into preference, rationale, examples, and escalation paths. Some repetition exists between 'PREFER OVER WEB SEARCH' and 'START HERE', and the domain list is extensive, but most sentences add selection-relevant value. It earns a 4 rather than 5 because it is slightly over-wordy.

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

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

There is no output schema, so the description must explain what the agent gets back, and it does: a structured answer with stable citation URIs. It also covers scope, trigger phrases, examples, sibling escalation paths, tier behavior, and adaptability to breaking news. For a high-complexity default router, this is complete enough for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, with the main 'question' parameter and all aliases documented in the schema itself. The description contributes little to parameter semantics except reinforcing that the input is a natural-language question. Baseline 3 is appropriate because the schema already carries the full parameter burden.

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

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

The description clearly states a specific verb and resource: it routes a user's factual question to the right tool among 5,724 verified sources and returns a structured answer with citation URIs. It strongly distinguishes itself from web search and from siblings like ask_pipeworx_grounded and deep_research. The examples reinforce the scope without ambiguity.

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

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

The description gives explicit when-to-use guidance: prefer over web search for factual/current/historical questions, use as the start-here default, and 'step up only when needed' to grounded or deep_research. It also provides concrete triggers like 'what is', 'look up', 'get the latest', and example queries. This is unusually actionable routing guidance.

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

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

Annotations already cover safety (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description carries a lighter burden yet still adds rich behavioral context: the current state ('No candidate is active right now... currently matches ask_pipeworx exactly'), the live-swapping behavior when a candidate is under test, and the critical assurance 'Falls back to nothing — this IS a full working router, just the experimental edge.' This refutes the likely assumption that a beta tool might be a stubbed proxy.

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 dense sentences, each earning its place: identity, live status, usage directive, and the working-router reassurance. The core identity is front-loaded ('Beta version of ask_pipeworx'). The only minor redundancy is that 'identical universal router' and 'Falls back to nothing — this IS a full working router' restate a similar point from different angles, but the latter addresses a real agent misconception so it earns its keep.

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

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

For a complex tool routing to 5,724 tools with no output schema, the description resolves the key uncertainties an agent would have: Is this a stub? (No — full working router.) Is it currently different from stable? (No — no active candidate.) What happens with results? (Compared to decide merges.) What safety profile? (Covered by annotations.) The response shape reference to ask_pipeworx plus the alias-heavy schema leaves no critical gap.

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

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

Schema description coverage is 100% — the schema documents question and all five aliases (q, text, input, query, prompt) with descriptions. The description adds nothing parameter-specific beyond noting 'same arguments' as ask_pipeworx, so the baseline of 3 applies: the schema does the heavy lifting and the description doesn't need to compensate.

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

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

The description names the exact relationship to its stable sibling ('Beta version of ask_pipeworx: identical universal router') and quantifies scope ('same 5,724 tools, same arguments, same response shape'). It clearly distinguishes this from ask_pipeworx and ask_pipeworx_grounded by framing it as the experimental edge used to test routing improvements.

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

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

Gives an explicit usage directive: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the purpose (results compared against stable router to decide merges), which tells the agent why choosing this variant matters. However, the when-not-to-use case (prefer the stable ask_pipeworx when you don't want experimental behavior) is only implied, not stated as an exclusion.

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

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

Annotations already mark it read-only, idempotent, and non-destructive, so the description's additional detail is highly valuable: it discloses refusal behavior, all refusal reason values, the exact return shape, and that it costs an extra LLM call. It even names the tool's conservative extraction policy. This goes well beyond annotation coverage.

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

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

The description is dense but every sentence earns its place: purpose, routing, extraction behavior, return contract, refusal semantics, use cases, and cost trade-off. It front-loads the distinguishing value and avoids filler. Despite its length, it is efficiently structured.

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

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

Given there is no output schema, the description fully compensates by spelling out both success and refusal response shapes, listing refusal reasons, and covering cost and routing trade-offs. An agent has enough to decide, invoke, and interpret results correctly.

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

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

Schema coverage is 100% and the description doesn't add much parameter-specific meaning beyond what the schema already documents. That's acceptable: the one required parameter, question, is self-explanatory and the aliases are fully listed in the schema. 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, differentiated purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly states the mechanism—same routing as ask_pipeworx, then extraction limited to tool result—and names the direct sibling it contrasts with. This leaves no ambiguity about what the 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?

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples. It also tells the agent when not to use it: 'prefer ask_pipeworx for casual lookups.' This is exemplary usage routing.

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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description goes far beyond this by disclosing account/paid-tier requirements, expected latency (15-60s, up to ~90s for thorough), the gaps[] behavior (never invented), contradictions[] scan, semantic excerpting, hop field, and citation_uri resolvability. This gives the agent a realistic model of execution cost and output guarantees.

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, and the most critical information is front-loaded: account requirement and fallback tool first, then the core capability, then usage guidance, depth semantics, output structure, and latency. It is dense with no filler or repetition of schema contents.

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

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

Even without an output schema, the description fully covers what an agent needs: prerequisites, exact output shape (findings packet with evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop), fallback behavior for unsupported topics, and performance expectations. Nothing essential for correct invocation or interpretation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics: it explains that depth:"thorough" incurs a paid plan, and it maps depth values to behavioral outcomes ('standard re-angles unanswered gaps', 'thorough additionally chases the best leads'), which directly helps an agent choose the right enum value. It also clarifies that the question parameter welcomes broad/multi-part natural language since decomposition is the point.

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?

States a specific verb ('research'), a precise resource ('Pipeworx's 1497 STRUCTURED data sources'), and explicitly disambiguates from open-web search. It also names what it is not (NOT open-web search) and contrasts with sibling tools like ask_pipeworx. An agent can clearly identify when this tool applies.

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

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

Gives explicit when-to-use: best for broad/multi-part questions over structured data. Provides explicit when-not-to-use and alternatives: single lookups go to ask_pipeworx, breaking/current-news topics prefer ask_pipeworx because deep_research returns empty gaps[]. Also states a hard prerequisite: requires a signed-in account, otherwise use ask_pipeworx. This is model-guidance beyond what any schema could convey.

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 mark the tool as read-only and idempotent, but the description adds substantial context: both modes run the same token-overlap matcher, 'unknown' legs are never paired, null temporal_alignment does not mean aligned, and spread values are gross of Kalshi fees. The skipped_cross_type/subtype counters and compatibility code semantics are also disclosed.

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 thorough but quite long, with multiple dense safety sections and enumerations. It is well-structured and front-loaded, but it is not concise — several paragraphs could be tightened without losing value.

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

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

With no output schema, the description carries full responsibility for explaining the response, and it does so extensively: leg prices, top_spreads_pp, compatibility fields, per-pair flags, temporal alignment semantics, fee disclosures, and skipped counters. An agent has nearly everything needed to call and interpret this tool safely.

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

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

Schema coverage is 100% and the description adds meaningful mode semantics, listing all ten topic shortcuts and explaining that explicit ticker/slug parameters override the topic-mapped side. This goes beyond the schema, though it is partly redundant with the per-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 states a specific verb and resource: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes itself from generic siblings by naming both venues and the token-overlap matching approach.

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

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

It provides explicit usage modes — topic shortcuts versus explicit kalshi_event_ticker + polymarket_event_slug pairing — and explains when each is appropriate. It also warns that pre-mapped topics often return warnings and that 'pre-mapped ≠ tradeable', giving the agent actionable guidance on when to trust the output.

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 (readOnly, idempotent, openWorld) already declare safety, but the description adds substantial behavioral context: cascading internal lookups, graceful degradation if GLEIF/OpenFIGI are unavailable, handling of ambiguous matches by returning figi_candidates, explicit reporting of unresolved identifiers, and ISIN-to-LEI resolution for non-US entities. It also mentions source labeling on each identifier, giving the agent a clear model of what happens during 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 a dense wall of text with a long parenthetical inside the SUPPORTED TYPES clause. Every sentence contributes valuable information, but the structure hampers scanning; a bulleted list or shorter paragraphs would improve readability. It is not tautological or empty, but it is over-stuffed relative to the ideal.

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

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

With no output schema, the description must carry the full burden of explaining return behavior. It covers input formats, types, edge cases (bonds, ambiguous matches, unresolved identifiers), failure behavior (graceful degradation), and even citation URLs for drug lookups. Nothing an agent needs to correctly invoke this tool or interpret its results is missing.

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

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

Schema coverage is 100% with detailed descriptions for both parameters, especially 'value' which includes examples and the bond-name warning. The description goes further by explaining the behavioral implications of the 'type' enum (company vs. drug) and what each type resolves to (e.g., company returns CIK, ticker, LEI, FIGI; drug returns RxCUI, ingredient, brand). This enriches the schema's bare enum, though the schema already carries the core instructions.

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

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

The description opens with concrete query examples and states the verb-resource pair: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It immediately distinguishes itself from siblings like entity_profile by framing itself as the ID-resolution step, and the 'Use FIRST' directive removes ambiguity. The supported types are explicitly enumerated (company, drug) with the identifiers each returns.

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 first sentence lists typical use cases (ticker, CIK, LEI, RxCUI lookups), and the description explicitly instructs 'Use FIRST whenever you have a name but need an ID.' It further clarifies when not to over-interpret a name (e.g., for bonds, pass the issuer exactly as printed), and notes that it replaces 2-3 manual lookups, setting expectations for when it is the efficient choice.

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

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.