Openstates

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. Description adds behavioral details: probes multiple models, returns per-model {score, confidence, signals, raw_response}, combined view, default free model, requires API key for Anthropic. 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?

Three sentences, front-loaded with verb 'Probe'. Each sentence adds essential information: main action, default/optional config, return structure, use cases. No wasted words.

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

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

No output schema, but description details return format per model and combined view. All four parameters explained. Complexity is low-moderate, and description is fully sufficient for correct invocation.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: explains 'entity' as thing to ask about, lists supported models (workers-ai, anthropic), clarifies '_apiKey' requirement, and 'context' for disambiguation. Adds value 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 states it probes LLMs for knowledge about an entity, scores visibility 0-100. Verb 'Probe' with resource 'LLMs' and output 'score' is specific. Distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on visibility scoring per model.

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

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

Explicitly says 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' Provides context for when to use, but lacks explicit when-not-to-use or alternatives. Mentions default model and optional API key, giving clear guidance on configuration.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns structured answers with stable pipeworx:// citation URIs and that it is 'one fast call', providing useful behavioral context 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 well-structured with clear sections: preference statement, capabilities, when-to-use, examples, and escalation guidance. While slightly verbose, every sentence is purposeful and front-loaded with the key 'PREFER OVER WEB SEARCH' directive.

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 4,396 sources, the description is remarkably complete. It covers purpose, usage guidelines, examples, return format (structured answer with citation URIs), and tier compatibility, leaving no major gaps given the rich annotations and absence of 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?

Schema coverage is 100% with all parameters described. The description adds no extra parameter details beyond the schema but includes many question examples that illustrate usage, adding value beyond the schema alone.

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

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

The description clearly states the tool routes questions to one of 4,396 tools across verified sources, providing a specific verb and resource. It distinguishes from siblings like web search and ask_pipeworx_grounded by noting its preference over web search and its role as the default entry point.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and gives clear when-to-use criteria (factual questions about real-world entities) and when to step up (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for multi-part questions). Provides numerous examples and specifies it works on every tier.

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

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

Description discloses behavioral traits beyond annotations: costs one extra LLM call, extracts answer only from tool results, returns explicit refusal reasons (not_in_source, no_tool_match, etc.). No contradiction with readOnlyHint=true.

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?

Description is well-structured, front-loading the core purpose, then explaining behavior, usage, and response format. Every sentence adds unique value without redundancy. Length is appropriate for the complexity.

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

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

Given no output schema, description fully details return format ({answer, evidence, confidence, source, ...}) and refusal cases. Parameter semantics are fully covered by schema. Context signals indicate moderate complexity; description is complete enough for correct agent invocation.

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

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

Schema coverage is 100% with clear parameter descriptions and aliases. Description doesn't add significant parameter-level detail beyond 'fills arguments', but schema already covers meaning sufficiently. 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 defines the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes it from ask_pipeworx by noting the extra LLM call and explicit refusal handling. It specifies verb+resource: answering with evidence only.

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: 'whenever an answer will be quoted, cited, or acted on' and for domains like financial verdicts, legal claims, etc. Also advises preferring ask_pipeworx for casual lookups, providing clear differentiation.

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 extensively discloses behavior beyond annotations: fan-out examples, response shapes, resolver contract, parent event extraction, news fallback handling, safety mechanisms (low confidence suppression, closed market handling, wide spread warnings), and resolution-rule risk. No contradictions with annotations.

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

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

The description is very long and contains extensive detail that could be structured or referenced elsewhere (e.g., output schema). While informative, it violates conciseness. Front-loading with core purpose helps, but the length may overwhelm agents.

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 3 parameters, no output schema, but the description comprehensively covers return shapes, edge cases, error conditions, and behavioral nuances. All necessary context for correct tool invocation and result interpretation is present.

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?

All three parameters have full schema coverage. The description adds meaning beyond schema: market parameter can be slug, URL, or question text; depth enum explained; include_raw parameter detailed with size and use-case context. The examples provide concrete input formats.

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 researches Polymarket bets by pulling Pipeworx data, resolving markets, classifying bets, and returning evidence. It specifies input types and gives concrete use cases. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on research and evidence gathering.

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 ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and provides detailed guidance on when it short-circuits (low confidence, closed markets, wide spreads). However, it does not explicitly state when to use alternatives or when not to use this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context like fiscal year handling for companies, sorting by primary metric, and citation URIs. While it doesn't cover all possible behaviors, it adds meaningful value beyond annotations.

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

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

The description is front-loaded with common query patterns and is informative but somewhat dense. Every sentence adds value, but it could be slightly more structured (e.g., separate lines for company vs drug). Still, no wasted words.

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

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

With no output schema, the description covers return format ('paired data + citation URIs'). It also explains substitution value ('Replaces 8-15 sequential lookups'). For a tool with 2 parameters and no nested objects, this is nearly complete, though exact structure of paired data could be more explicit.

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 significantly enriches parameter understanding: it explains that type='company' pulls SEC financials and type='drug' pulls FAERS/trial data, and specifies values format (tickers/CIKs for company, names for drug). This goes well beyond the schema's minimal 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 explicitly states it performs side-by-side comparison of 2-5 companies or drugs, using specific verbs like 'compare', 'rank', 'head to head'. It clearly distinguishes from siblings like entity_profile by emphasizing parallel lookups over sequential ones.

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.' It also lists common query patterns (e.g., 'X vs Y', 'which is bigger') that trigger this tool, giving clear context for selection.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds: account required, free tier limitations, expected 15-60s response, returns gaps[] for unanswered facets, and never invents data. No contradiction.

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

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

The description is longer but well-structured: account info first, then core functionality, then usage guidance, then output details. Every sentence adds value, though some redundancy exists (e.g., 'not open-web search' repeated).

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, the description covers input (broad questions), behavior (parallel decomposition), output (findings with evidence and gaps), prerequisites (account), and performance (15-60s). No output schema needed as the output is described sufficiently.

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% (baseline 3). The description adds value by explaining enum semantics (quick=3, standard=5, thorough=8 facets) and emphasizing that questions can be broad/multi-part, which is not clear from the schema alone.

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

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

The description explicitly states the tool performs grounded multi-source research across 1,127 structured data sources, decomposes questions into facets, and returns a findings packet. It distinguishes itself from siblings like ask_pipeworx and clarifies it is not open-web search.

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 (broad/multi-part questions over structured data) and when-not-to-use (single lookup: use ask_pipeworx; breaking news: prefer ask_pipeworx). Also notes account requirements and fallback for unsigned users.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds value by explaining the output format (top-N tools with schemas) and that results are ready to call directly. 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?

Six sentences, front-loaded with purpose, no redundant information. Every sentence adds value (scope, usage, return format).

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 role as a discovery gateway, the description fully covers purpose, usage, input, and output. No output schema is needed because the tool returns tool definitions with schemas.

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 descriptions; description adds alias information (task, q, description, search) and contextualizes query as natural language. This goes beyond the schema's 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 clearly states 'Find tools by describing the data or task' and lists specific domains (SEC filings, financials, etc.). It distinguishes this meta-tool from sibling domain-specific tools by emphasizing discovery and browsing.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set'. Provides clear when-to-use and implies alternatives (direct tool calls).

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. Description adds critical context: fan-out across multiple sources, PatentView API sunset with soft-fail, GDELT→GNews fallback, return structure with URIs and sorted data. This goes well beyond annotations.

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

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

Description is detailed but well-structured with examples and bullet points. Every sentence adds value, but the length could be slightly reduced without losing essential information. Still, it is front-loaded with examples and immediately clear.

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

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

Given the complexity (multiple data sources, no output schema), the description comprehensively covers return fields, data sources, constraints (ticker/CIK only, PatentView sunset), and fallback behavior. Annotations cover safety; description covers everything else needed for correct invocation.

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

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

Schema coverage is 100% with both parameters described. Description adds that type enum only supports 'company' for now, value should be ticker or zero-padded CIK, and explicitly states that names are not supported. This adds 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?

Description clearly states the tool retrieves a full cross-source profile of US public companies. It opens with example queries ('Tell me about X', 'research Acme') and lists specific data sources (SEC, XBRL, USPTO, news, GLEIF) and return fields. This specificity and the verb+resource combination strongly distinguish it from sibling 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?

Explicitly states to prefer this tool over chaining single-pack lookups when a holistic view is needed. Also notes that names are not supported and directs users to use resolve_entity if they only have a name. This provides clear when-to-use and when-not-to-use 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 indicate destructive (destructiveHint=true) and idempotent (idempotentHint=true). Description adds 'Delete by key' but no further behavioral details (e.g., confirmation, effect on related data). Does not contradict 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, efficient and front-loaded. Every sentence adds value: action, usage context, and pairing with siblings.

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 simple tool (1 param, no output schema, clear annotations), description adequately covers purpose, usage, and pairing. Lacks note on return value or error cases, but output schema absent so not required.

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?

Single required parameter 'key' with schema description 'Memory key to delete'. Schema coverage is 100%, so baseline 3. Description adds no extra meaning 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?

Clear verb 'Delete' with resource 'previously stored memory by key'. Immediately distinguishes from siblings like remember and recall by specifying 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?

Explicitly states when to use (stale context, task done, clear sensitive data) and pairs with related tools (remember, recall). Lacks explicit when-not or direct alternatives, but the context is sufficient.

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

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

The description details the tool's behavior (fetching page, extracting title/description/key links, emitting standard format) beyond the annotations (readOnlyHint, idempotentHint, etc.). It adds useful context about the output being a single text blob ready for deployment.

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

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

The description is concise, front-loaded with the core purpose, and every sentence adds value. It avoids redundancy and is easy to parse.

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

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

Given the rich annotations, full schema coverage, and clear output description (standard markdown blob), the description is complete enough for an AI agent to understand the tool's purpose and behavior. It could mention rate limits or error handling, but it's sufficient for typical use.

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 an example for 'url' but does not provide additional meaning for 'max_links' beyond the schema's description. No contradiction or elaboration.

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 specifies the action ('Generate a production-ready llms.txt file'), the target (any URL), and the format (standard llms.txt markdown). It is distinct from sibling tools, none of which provide similar functionality.

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 lists three explicit use cases: getting a client's site indexed, drafting llms.txt for your own project, and auditing competitor visibility. It does not specify when not to use it, but the use cases are clear and cover the primary scenarios.

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, destructiveHint, idempotentHint, and openWorldHint. The description adds context about what specific data is returned (versions, sponsorships, etc.), enhancing transparency beyond annotations.

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

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

Two sentences: the first states the purpose and what is fetched, the second explains parameter usage. Extremely concise, front-loaded, and every sentence adds 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?

Given the output schema exists (though not shown), the description covers all necessary aspects: what the tool does, how to use it, and what it returns. It is complete for the complexity of the tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value by explaining the logic behind using openstates_id as a single identifier vs. the triple (session+identifier+jurisdiction), and provides examples that clarify usage.

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

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

The description clearly states it fetches a single bill with full detail, listing specific components like versions, sponsorships, actions, and votes. It explicitly distinguishes from sibling search_bills by focusing on a single bill with all details.

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 two clear ways to identify the bill (by OpenStates ID or by session/identifier/jurisdiction triple) and indicates which is preferred. While it doesn't explicitly state when not to use, the context and sibling names make the use case 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, idempotent, and non-destructive behavior. The description adds value by listing what the tool returns (biographical info, roles, offices, contacts, sources) without contradicting annotations.

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

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

A single, well-structured sentence that front-loads the core action and clearly lists what the tool returns. No extraneous information.

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

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

Given the simplicity of the tool (one parameter, no nested objects) and the presence of an output schema, the description fully covers input, output, and purpose.

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 the person_id parameter well. The description merely repeats 'by OpenStates person ID', adding no new semantics beyond the schema.

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

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

The description clearly states the verb (Fetch), resource (legislator), and unique identifier (OpenStates person ID). It distinguishes from search tools like '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 specifies when to use (to fetch a single legislator by ID) but does not explicitly state when not to use or mention alternatives, though sibling tool 'search_legislators' implies the 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 readOnlyHint and idempotentHint. Description adds that it returns specific fields and mentions the default is active subscriptions only, going beyond annotations.

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

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

Two concise sentences: first covers purpose and return fields, second provides usage guidance. No wasted words.

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

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

For a simple list tool with one optional parameter and annotations covering safety, the description fully covers purpose, return fields, and usage context. No output schema needed as return fields are described.

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 100% of parameter descriptions. Description does not add new parameter-level detail beyond what schema provides, so baseline 3.

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?

Clearly states 'List the caller's active subscriptions' and lists specific return fields (id, type, params, created_at, last_fired_at, fire_count). Distinguishes from sibling tools like subscribe 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?

Provides explicit usage scenarios: 'review what you're monitoring before adding more or to find an id to cancel.' Does not mention alternatives but context is sufficient.

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

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

The description fully compensates for the lack of behavioral annotations (all false) by disclosing key traits: rate limit (5 per identifier per day), free usage, no quota impact, and how feedback is processed (daily digests affecting roadmap). No contradictions with annotations.

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

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

The description is concise yet comprehensive, front-loading the core purpose. Every sentence serves a purpose: purpose, use cases, formatting guidelines, rate limits, and impact. No wasted words.

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

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

Given the tool's complexity (3 params, nested object, no output schema), the description is complete. It covers purpose, usage guidance, parameter meanings, rate limits, and processing expectations. No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the enum values for 'type' (e.g., bug, feature) and emphasizing that context should be in terms of Pipeworx tools/packs. This goes 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's purpose: to send feedback to the Pipeworx team about bugs, missing features, or praise. It uses a specific verb (tell) and resource (Pipeworx team), and distinguishes itself from sibling tools like ask_pipeworx or discover_tools.

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

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

The description explicitly defines when to use the tool: for bugs, feature requests, data gaps, or praise. It also provides guidance on what not to do (e.g., don't paste the end-user's prompt), making it clear when to use this tool versus alternatives.

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

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

Beyond annotations (readOnly, idempotent), description adds data source (CF analytics-engine), no PII, caching behavior (5min-1h), and return structure. Fully informs agent of 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?

Concise with front-loaded output statement, bullet-style use cases, and supplementary details. Every sentence adds value with no redundancy.

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

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

For a simple tool with single parameter and no output schema, description covers purpose, use cases, data origin, privacy, and caching. Complete and self-sufficient.

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

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

Schema coverage is 100% with one enum parameter. The description adds semantic context: shorter windows surface hot trends, longer show steady-state demand, complementing 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 it returns top tools, top packs, and call volume with specific use cases, distinguishing it from siblings like 'discover_tools' or 'ask_pipeworx' by focusing on 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?

Three explicit use cases are given (discovering hot data sources, confirming canonical tools, aligning use cases). Lacks explicit 'when not to use' or alternative tool names, but context is sufficient.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds detailed behavioral context: monotonicity checks, partition sum checks, Jaccard similarity filter, placeholder filtering, fill check with live CLOB depth, and trade recommendations. 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?

Description is verbose but well-structured and front-loaded with key requirement. Every sentence adds value given the tool's complexity, though could be slightly more concise.

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

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

Despite no output schema, the description fully explains the response structure (opportunities array, partition_check, fill check) and references related tool for custom sizing. Covers all necessary aspects for a complex arbitrage 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 descriptions, but the tool description adds significant value: expands on parameter semantics with examples, usage recommendations, and detailed behavior per mode. Exceeds baseline of 3.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks, distinguishes between single-event and cross-event modes, and provides examples. It is specific and distinguishes from sibling tools by focusing on arbitrage computation.

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 'event' vs 'topic', warns that no args fails, recommends 'event' for specific markets, and gives example slugs and seed questions. Provides clear usage context without needing external references.

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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds extensive behavioral details: caching at KV level keyed on all knobs with 1-hour TTL, breakdown of three segments, how edge_pp_net is calculated net of slippage, and diagnostics for empty segments. No contradictions with annotations.

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

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

The description is lengthy but well-structured, starting with the core purpose and then detailing each segment and knob. It is front-loaded with the most important information. While some parts are dense, every sentence adds value, justifying its length 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?

Given the tool's complexity (9 parameters, no output schema), the description is exceptionally complete. It explains the response structure (by_segment, _diagnostics), caching behavior, and edge cases like Fed bets. It compensates for the lack of an output schema by detailing what each opportunity contains.

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 descriptions for all 9 parameters. The description adds further context beyond the schema, such as explaining why min_kelly does not filter partition opportunities and how slippage_pp interacts with Polymarket's fee structure. This enhances understanding of parameter usage.

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

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

The description clearly defines the tool as scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price, explicitly stating 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on edge detection across multiple model families.

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 on when to use the tool (discovering opportunities without paging hundreds of markets) and includes specific knobs for filtering tradeable edges. It notes that Fed bets are excluded, offering some guidance on when not to rely on the tool. However, it does not explicitly mention alternative tools for specific use cases.

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

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

The description adds significant behavioral context beyond annotations: it details the response structure (tracked, expired, snapshot_dates), explains limits (60-day TTL, decay from daily closes not intraday), and provides examples. Annotations already indicate read-only, open-world, idempotent, non-destructive, so the description complements them well.

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

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

The description is comprehensive but somewhat lengthy; however, each sentence adds valuable information. The core question is front-loaded, and the response structure is clearly laid out. Could be slightly more concise but overall well-organized.

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 absence of an output schema, the description thoroughly explains the response fields (tracked, expired, snapshot_dates) and their semantics, along with limits and data origins. This provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100% with clear parameter descriptions. The description restates the parameters (days, window) without adding new semantic meaning. No additional guidance on parameter interplay or edge cases is provided.

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 it provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific question about edge age and trend. This distinguishes it from siblings like polymarket_edges which likely provides current snapshot data.

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 when to use this tool (when historical persistence and decay matter) but does not explicitly state when not to use it or name alternatives like polymarket_edges for current snapshots.

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 context about what the tool returns (e.g., ladder walking, VWAP fill, slippage, verdict) and explains the risk of partial fills in basket mode (converting arb into unhedged directional position). This provides useful behavioral insight beyond annotations.

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

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

The description is relatively long but well-structured with clear sections (overview, mode-specific details, return fields, usage advice). It is front-loaded with the core purpose. While every sentence adds value, some repetition could be trimmed for conciseness.

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

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

Given the complexity (two modes, many return fields) and the absence of an output schema, the description comprehensively lists expected outputs for each mode (including verdict, thin_legs, forced_directional_risk) and explains the key risks. The rich annotations complement this, making the description complete for an AI agent to understand the tool's behavior.

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

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

Schema description coverage is 100%, but the description adds value by providing default values (size_usd default 1000, clamp range) and clarifying the interpretation of parameters across modes (e.g., side default auto in basket mode based on partition sum). This goes beyond what the schema alone provides.

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

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

The description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' with two distinct modes (single-market and basket). It explicitly distinguishes from siblings by naming 'polymarket_arbitrage' and 'polymarket_edges' and specifying when to use this tool before those actions.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the risks of not using it (partial fills causing unhedged directional positions) and requires one of 'market' or 'event' parameters, clearly delineating the two modes.

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

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

Despite annotations already indicating a safe read-only operation, the description goes far beyond by detailing compatibility warnings, temporal alignment, and leg-matching logic. It sets realistic expectations about the prevalence of tradeable spreads.

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

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

The description is well-structured and front-loaded with the core purpose. It is informative but slightly verbose, especially in the safety fields section. Every sentence adds value, but some could be more concise.

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

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

Given the complex nature of cross-venue comparison with no output schema, the description thoroughly explains response structure, safety fields, and edge cases. It provides sufficient information for the agent to understand what the tool returns.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context about modes and auto-fetching but does not significantly enhance parameter 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 clearly defines the tool as a cross-venue spread calculator between Kalshi and Polymarket. It specifies two modes (macro shortcuts and explicit pairing) and distinguishes itself from sibling tools like polymarket_arbitrage through its cross-venue focus.

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 guidance on when to use the tool, including explicit scenarios for both modes and warnings about compatibility issues. It lacks direct comparison to the sibling tool polymarket_arbitrage, but the context is strong.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds scoping detail and dual behavior (retrieve vs list), providing value beyond annotations.

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

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

Three sentences: first defines action, second gives examples, third scoping and pairings. Front-loaded, no wasted words.

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

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

Given single optional parameter, full schema coverage, and clear annotations, the description adequately covers all needed aspects: retrieval, listing, scoping, and sibling relationships.

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 the single parameter with 100% coverage. Description reinforces schema and adds usage context (pairing with remember, omission for listing), enhancing 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?

Description clearly states the tool retrieves a value by key or lists all keys when omitted, and explicitly distinguishes from sibling tools remember and forget.

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

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

Provides explicit use cases (look up stored context like ticker, address, research notes) and scoping (by identifier). Does not explicitly state when not to use, but context 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?

Description states that setting 'mark_read:true' flags returned events as read, implying a state mutation. This contradicts the annotations which declare 'readOnlyHint: true', suggesting no state changes. The contradiction score is mandatory as per guidelines.

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 only three sentences, front-loaded with purpose and return fields, no wasted words.

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

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

Covers purpose, return fields, filter options, mark_read behavior, and alternative access. Minor omission: does not explain 'unread_only' parameter, though schema covers it.

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

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

Schema coverage is 100%, and the description adds extra meaning beyond the schema, such as example filter values ('sec_8k') and the effect of 'mark_read'.

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

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

The description uses a specific verb 'Pull' and resource 'fired events from your subscription feed', and details the return fields. However, it doesn't explicitly distinguish this tool from sibling tools like 'recent_changes' or 'list_subscriptions'.

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?

No explicit guidance on when to use this tool versus alternatives. It mentions polling is fine and provides an alternative HTTP endpoint, but does not compare with 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses parallel external calls, fallback logic (GDELT→GNews), soft-failure for USPTO, and the output structure (grouped changes, citation URIs). 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 slightly verbose but each sentence adds necessary detail. It is front-loaded with purpose and includes structured source explanations. Minor redundancy could be trimmed, but overall effective.

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 complexity (3 required params, no output schema, rich annotations), the description fully covers behavior, parameters, fallbacks, and limitations like USPTO sunset. Leaves no critical gaps for an agent to understand invocation.

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

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

Schema has 100% coverage; description adds value by explaining `since` format (ISO date vs relative shorthand) and providing typical values like '30d'. Also clarifies `type` is restricted to 'company'.

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

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

The description clearly identifies the tool as a change feed for recent updates on a company, with explicit examples like 'latest on Y' and 'updates on Acme'. It distinguishes itself from the sibling tool entity_profile, which serves a static profile regardless of time window.

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 context, including when to use (e.g., 'what happened to Z this week') and when not to (use entity_profile for static profile). Details the parallel fan-out to multiple data sources and fallback behavior, giving agents clear 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 indicate idempotent and non-destructive behavior; the description adds details on persistence (permanent vs 24-hour) and scoping, going beyond annotations.

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

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

Four sentences, front-loaded with purpose, no redundant information.

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

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

For a simple 2-param tool with no output schema, the description covers persistence, scoping, and pairing, providing complete context.

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

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

Schema covers both parameters with descriptions; the description adds examples for key and clarifies value is free-form text, adding 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 uses a specific verb ('save') and resource ('data'), and clearly distinguishes from sibling tools by mentioning 'recall' and 'forget'.

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 clear usage context ('when you discover something worth carrying forward') and pairs with other tools, but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructiveness, so the safety profile is clear. The description adds value by explaining that each call cascades through multiple lookup endpoints internally and replaces 2-3 manual lookups. It also details the exact return fields for each type, which is 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 well-structured with example queries at the start, followed by detailed breakdowns of supported types. It is front-loaded with the key usage guidance. While slightly verbose, every sentence adds value, and the structure aids readability.

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 absence of an output schema, the description adequately explains what each entity type returns, including specific fields and citation URIs. It covers the main use cases and mentions auto-disambiguation for companies. However, it does not address edge cases like ambiguous input or error behavior, which prevents a perfect score.

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 has 100% description coverage for parameters, so baseline is 3. However, the tool description adds meaning by specifying the return format for each type (e.g., ticker + CIK + company_name + citation URI for companies). This enriches the agent's understanding of how the parameters map to results, justifying a score above baseline.

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

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

The description uses specific verbs and resources: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It lists example queries and explicitly states the supported entity types (company, drug) with clear distinctions on what each returns. This makes the purpose unambiguous and easily understood.

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 a clear when-to-use directive: 'Use FIRST whenever you have a name but need an ID.' It also includes example queries that illustrate the mental model. However, it does not explicitly state when not to use this tool or mention alternative tools for similar tasks, which prevents a score of 5.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds how it works (probes each entity, ranks by score) and what it returns (score, confidence, signal density). 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?

Three sentences: purpose, method, use case and return. Front-loaded, no fluff, every sentence adds 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 covers return format. It explains the context parameter. Could mention entity count constraint (2-8) but schema already specifies minItems? Not in schema, but description mentions 'multiple entities'. Slightly incomplete but good overall.

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. The description adds meaning beyond schema: first entity is treated as subject, context disambiguates common names. This provides useful context for parameter usage.

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

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

The description clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, and ranks results. It distinguishes itself from the sibling tool ai_visibility_check, which likely checks a single entity.

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

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

The description explicitly says it's useful for competitive AI-marketing audits and positions itself as a multi-entity comparison. It implies using ai_visibility_check for single checks, but does not explicitly state when not to use this tool.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant behavioral context: it fans out to two sources, details return fields (summary, advisories, links, alternatives), explains partial failures degrade gracefully, and notes that bundlephobia's first measurement can take 5-30s. 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 three sentences with efficient, front-loaded content. The first sentence states the core purpose, followed by usage context and return details. Every sentence adds value, and there is no redundancy or fluff.

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

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

Despite lacking an output schema, the description comprehensively covers the return structure (summary block with specific fields, per-advisory detail, links, alternative versions) and edge cases (partial failures, timeout behavior). It is complete for the tool's complexity and provides sufficient context for an agent to understand what to expect.

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

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

Schema description coverage is 100% with adequate descriptions for both parameters. The description adds extra meaning: that scoped packages (e.g., '@types/node') are accepted, and that version defaults to the latest. This goes beyond the schema's baseline, justifying a score above 3.

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 it is a composite check for npm packages that aggregates data from deps.dev and bundlephobia. It distinguishes this tool from siblings by specifying the NPM ecosystem scope and noting that other ecosystems fall under a different tool (deps.dev:version).

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

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

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also explicitly states when not to use: for non-NPM packages, use deps.dev:version directly. This provides clear context for when to choose this tool over 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 indicate read-only, idempotent, and non-destructive behavior. The description adds that it searches across any US statehouse and returns bill identifiers, titles, classifications, sponsors, etc. It does not mention pagination limits or rate limits, but the schema covers page/per_page. Overall, it provides useful context beyond annotations.

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

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

The description is two sentences covering purpose and key parameter guidance. It is front-loaded, efficient, and contains no redundant information.

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

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

With an output schema already available, the description does not need to detail return values. It covers the essential use case and jurisdiction parameter. However, it could briefly mention that full-text search is available via the query parameter or that results are paginated, but the schema provides these details. Overall, it is sufficiently complete for an 8-parameter tool with 100% schema coverage.

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 each parameter is already described there. The description adds clarity for the jurisdiction parameter (explicitly accepting full state names) and mentions that results are intended for get_bill, but does not add meaning for other parameters like sort, session, or classification 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 it searches bills across US statehouses, specifies that jurisdiction is required, and lists the return fields including identifiers for use with get_bill. This distinguishes it from sibling tools like get_bill (which retrieves a single bill) and search_legislators (which searches 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 gives explicit guidance on passing jurisdiction as a two-letter code or full name, and mentions that results include OpenStates IDs for subsequent get_bill queries. However, it does not explicitly state when to prefer search_bills over siblings (e.g., use get_bill for a known bill, search_bills for discovery).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds return field details, which are also in the output schema, so minimal additional 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?

Two sentences: first states purpose, second lists filters and returns. No unnecessary words, front-loaded with key information.

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

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

Given 7 optional parameters and an output schema, the description covers the tool's purpose, available filters, and return fields. Pagination parameters (page, per_page) are in schema but not mentioned, but that's acceptable for a search tool with clear annotations.

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 descriptions for all 7 parameters. The description summarizes filter types (jurisdiction, name, chamber, party, district) but does not add meaning 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?

Description clearly states the tool finds state legislators and lists filterable fields (jurisdiction, name, chamber, party, district) and return fields (name, roles, party, contact, IDs). This distinguishes it from sibling tools like search_bills or get_legislator.

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?

Description explains filters but does not explicitly state when to use this tool versus alternatives like get_legislator. However, the context implies it's for list searches, and the filters guide usage.

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 all key behavioral traits beyond annotations: it returns passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, has a 200K char cap with truncation and flagging. These details are not in the annotations and add significant transparency. There is no contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint), which only describe safety/idempotency.

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 paragraph of four sentences, each serving a distinct purpose: purpose, usage guidance, pairing context, and technical details. It is front-loaded with the core action ('Semantic search INSIDE a fetched record'). While the fourth sentence detailing embeddings and window size might be considered slightly technical, it is justified for transparency. No sentence is wasted, and the overall length is appropriate.

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 (semantic search with chunking and embedding), the description covers all essential aspects: input (text + query), output format (passages with offsets and scores), behavior (chunking, similarity, truncation), and integration hints (pairing with ask_pipeworx_grounded). The input schema fully documents parameters, and the description adds the missing output schema details. Annotations cover safety. No critical gaps remain.

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

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

Schema coverage is 100% with each parameter described. The description adds meaning beyond the schema by explaining the 'text' parameter as 'the text you already pulled', the 'query' as a natural-language query with examples, and the 'limit' with a default value. It also mentions the 200K char cap and truncation behavior, which augments the schema's max constraint. This provides richer context for why and how to set each parameter.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using verbs 'search INSIDE' and 'get back passages'. It distinguishes from sibling tools like ask_pipeworx_grounded by explicitly pairing and contrasting: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' The specific mention of returning character offsets and similarity scores further clarifies the unique output.

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

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

The description provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' It also outlines a prerequisite ('Pass the text you already pulled'). While it does not explicitly state when not to use it, the context implies that if the text is small, it might not be needed. It also mentions pairing with ask_pipeworx_grounded, indicating a workflow.

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

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

Annotations indicate non-read-only, non-destructive, idempotent, and open-world. The description adds critical behavioral context: requires OAuth, phone verification for SMS, 10 SMS/day cap, webhook auto-disable after 10 failures, and always-on feed. 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 relatively long but well-structured: it starts with the core purpose, then covers requirements, types, and delivery details. Every sentence adds value, though some detail could be condensed.

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 complexity (multiple subscription types, delivery options, constraints), the description is thorough. It covers prerequisites, type-specific parameters, delivery channels, and important limits. Missing error handling and idempotency details are minor gaps.

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 extra meaning by providing concrete examples for each subscription type and detailed delivery channel options, including constraints like phone verification and webhook HMAC signing.

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 new subscription id. It distinguishes itself from sibling tools like list_subscriptions (listing existing) and unsubscribe (removing) by focusing on creation.

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 the prerequisite (Pipeworx OAuth account) and lists supported subscription types with examples, guiding when to use each. However, it does not explicitly state when not to use this tool vs alternatives like one-off queries.

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 no destructive behavior. The description adds significant behavioral context: it returns categorized example questions with exact tool and argument shape, and describes the effect of calling with no arguments vs. with a topic. 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 a single paragraph that front-loads common user questions and provides detailed information. It is informative but slightly lengthy; every sentence earns its place, though some redundancy could be trimmed.

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

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

Given the tool has only one optional parameter, no output schema, and rich annotations, the description is complete. It covers purpose, usage timing, parameter behavior, and output structure, leaving no ambiguity for correct invocation.

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

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

Schema coverage is 100% and the schema describes the topic parameter with allowed values. The description enhances semantics by explaining that omitting topic gives a full cross-category spread, adding 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 is an onboarding entry point for learning what questions to ask Pipeworx. It uses specific verbs and resources: 'suggest_questions' returns 'category-bucketed example questions'. It distinguishes itself from siblings like ask_pipeworx and discover_tools by positioning itself as the first tool to use when unsure.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains when to pass the optional topic parameter and when to omit it, providing clear context for usage.

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 indicate a mutation (readOnlyHint=false) that is not destructive (destructiveHint=false) and idempotent (idempotentHint=true). The description adds valuable context: the row is deactivated not deleted, and historical events remain available via recent_alerts, providing full behavioral transparency without contradiction.

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

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

The description is two sentences with no redundant information. Every sentence adds value: the action, ownership constraint, and the deactivation nuance. Highly concise.

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

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

Given the single parameter, no output schema, and the annotations, the description fully covers the tool's behavior, constraints, and outcome. No gaps remain.

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

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

Schema coverage is 100% with a single parameter (id) described as 'Subscription id (uuid) returned by subscribe.' The description does not add additional semantic meaning beyond the schema, meeting the baseline expectation.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource (subscription). It also distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation behavior.

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

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

The description explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding the agent on appropriate use. However, it does not mention alternatives or explicitly state when not to use the tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, etc. The description adds significant behavioral context: returns a verdict (confirmed / refuted / etc.), extracted structured form, actual value with citation, percent delta, and that it replaces 4-6 sequential calls. 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 somewhat lengthy but well-structured with examples and a clear statement of replaces older workflow. It is front-loaded with key examples and purpose, earning its sentences.

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

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

Given the tool has a single parameter, no output schema, and annotations provide safety signals, the description fully explains the return format (verdict, structured form, citation, delta) and use case. It is 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 covers 100% of the single parameter 'claim' with a basic description. The description adds richer semantics by showing example claims and stating it accepts natural-language factual claims, which adds 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 explicitly defines the tool as a natural-language claim verification system against authoritative sources, with specific examples and mention of replacing multiple sequential calls. It clearly distinguishes its scope (company-financial claims via SEC EDGAR + XBRL) from siblings.

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

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

The description states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides query examples. However, it does not explicitly mention when to use alternative tools for non-financial claims, which would improve guidance.

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