Openparliament Ca

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

Discloses default model, API key pass-through, pricing implication, and output structure, adding substantial value beyond annotations which already indicate read-only 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?

One paragraph of 4 sentences, front-loaded with main action, no redundancy. Every sentence adds meaning: default, output, use cases.

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 simplicity, the description covers purpose, inputs, default behavior, output format, and use cases comprehensively. No missing information.

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 explaining default model for 'models' and how '_apiKey' enables Anthropic, beyond what the schema says.

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 'probe' and resource 'LLMs for visibility score', with specific output format. It distinguishes from siblings like ask_pipeworx and compare_entities by focusing on AI visibility scoring.

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 (AI-marketing audits, brand checks) and explains when to use the API key vs default model. Lacks direct comparison to alternatives, but purpose is distinct enough.

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 (readOnlyHint, idempotentHint, etc.) already establish the safe read-only nature, so the bar is lower, but the description still adds substantial behavioral context: it routes to 5,358 tools, fills arguments, returns structured answers with pipeworx:// citation URIs, and works on every tier. This goes well beyond the annotations without contradicting them.

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

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

The description is long but exceptionally well-structured, front-loading with 'PREFER OVER WEB SEARCH' and then layering purpose, triggers, examples, and alternatives. Each sentence earns its place by adding unique guidance, though it could be trimmed slightly without losing value.

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

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

For a tool that routes to 5,358 tools with no output schema, the description covers all critical aspects: what it does, what it returns (structured answer with citation URIs), when to use it, alternatives, and example queries. It gives the agent enough context to invoke the tool correctly and interpret the response.

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

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

The input schema covers 100% of parameters with clear descriptions, including aliases and examples, so the baseline is 3. The description adds no new parameter-level semantics; its examples and phrasing guidance are already present in the schema's examples. No additional credit is warranted.

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 ('routes', 'returns') and resource ('the right one of 5,358 tools across 1395 verified sources'), clearly stating the tool's core function. It also explicitly differentiates from web search and sibling tools like ask_pipeworx_grounded and deep_research, making its distinct role unmistakable.

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

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

The description opens with 'PREFER OVER WEB SEARCH' and lists specific domains and trigger phrases ('what is', 'look up', 'get the latest', etc.), then provides concrete examples. It explicitly names alternatives ('use ask_pipeworx_grounded', 'use deep_research') and clarifies when NOT to use them (breaking news), giving the agent complete when/when-not guidance.

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

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

The description goes beyond annotations by disclosing its beta status, that no candidate is currently active, and that it matches ask_pipeworx exactly at this time. It also explains the experimental purpose and that results drive routing improvements, providing rich behavioral context.

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

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

The description is four sentences long, each adding distinct information: beta status, current behavior, usage instruction, and reassurance that it is a full router. While slightly dense, it is well-organized and avoids redundancy.

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

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

The description thoroughly covers the tool's experimental nature, current status, and relationship to the stable router. It does not explain return values, but since it matches ask_pipeworx exactly and no output schema exists, the shared response shape is implied.

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

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

Schema description coverage is 100%, with all 6 parameters clearly documented as aliases for 'question'. The description adds no extra parameter meaning, but the schema is sufficient, so baseline 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, specifying it is a universal router with the same 5,358 tools and arguments. It distinguishes itself from the stable sibling by noting it is the experimental edge with potentially improved routing.

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

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

Explicit usage guidance is provided: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that results are compared against the stable router to decide what merges, giving clear context for when to prefer this beta 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?

Discloses the exact return structure including refusal reasons, and notes the extra LLM call cost. This complements the readOnlyHint/openWorldHint annotations with rich behavioral context about how the tool uses tool results and what happens when data doesn't answer. 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 moderately long but every sentence earns its place—covering behavior, return format, use cases, and costs. It is front-loaded with the core purpose and structured logically, though slightly dense for fast scanning.

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

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

Given the tool's complexity and lack of output schema, the description fully covers return values, success/error behavior (all refusal reasons), and when to use it. No critical aspect is missing, making it complete for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100% (all 6 parameters are documented as aliases for question), so the description adds no parameter-specific info needed. The description mentions 'fills arguments' but doesn't add syntax beyond the schema. Baseline 3 is appropriate as the schema does the heavy lifting.

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 identifies the tool as a hallucination-resistant answer mode for high-stakes reads, describes the routing and extraction process, and differentiates from sibling ask_pipeworx by noting same routing but grounded extraction. The verb 'answer' plus 'grounded' mode makes the purpose specific and distinct.

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

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

Explicitly specifies when to use: whenever an answer will be quoted, cited, or acted on and the agent must not invent facts, with concrete examples (financial verdicts, legal claims, medical lookups). Also provides an alternative: prefer ask_pipeworx for casual lookups, and includes the cost trade-off, making the guidance actionable and complete.

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?

Extensive behavioral details beyond annotations: fan-out logic per category, response shapes, resolver contract with confidence levels, parent event extraction, news fallback, safety shortcuts for low-confidence/closed markets, spread warnings, and cancellation rule parsing. All transparent.

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?

Long but every sentence is substantive and front-loaded with essential info (purpose, input format, classifiers). Could be slightly more concise but structure is logical with clear section headers. Earns its length.

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

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

Very complete given complexity: no output schema but explains output shapes in detail. Covers resolver contract, parent event, news fields, safety mechanisms, and edge cases. Agent can fully understand behavior without guessing.

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. Description adds value by explaining depth's effect (number of sources), encouraging include_raw=false for response size, and giving input format examples. 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?

Clearly states it researches a Polymarket bet by pulling Pipeworx data. Provides input formats (slug, URL, question text) and examples. Distinguishes from sibling tools like polymarket_edges by focusing on comprehensive data gathering and classification.

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 use cases given ('should I bet on X', 'what does the data say', 'is there edge'). Does not explicitly say when not to use or name alternatives, but the context is clear enough for an agent.

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

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

Annotations already mark it read-only, open-world, idempotent, non-destructive. The description adds significant behavioral detail: sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, result sorting, and citation URI provision. 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 front-loaded with example queries, then explains behavior per type, and ends with a benefit. Every sentence is informative; no filler. It is appropriately sized 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?

With only 2 parameters and full schema coverage, the description fully explains what to expect: paired data, citation URIs, sorted results. No output schema needed given the detailed behavior description.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond by explaining that for 'company' type it uses tickers/CIKs and pulls revenue/net income/cash/debt, and for 'drug' type it pulls FAERS counts. This adds meaningful context beyond schema descriptions.

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

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

The description clearly states it performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with explicit example phrases ('X vs Y', 'which is bigger', 'rank these companies'). It distinguishes itself from sequential lookups, making the purpose unmistakable.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides guidance on when to use (comparing entities) and what data each type returns. It lacks explicit when-not-to-use scenarios but is still very useful.

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?

Adds substantial behavior beyond annotations: requires account/paid plan, decomposes into facets, routes to 5,358 tools in parallel, returns findings with gaps[] and contradictions[], explains semantic excerpting, citation URI scheme, and latency. No contradiction with readOnlyHint or idempotentHint.

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?

Long but information-dense with critical access constraints and alternatives first, followed by capabilities, limitations, and timing. Every sentence adds distinct value 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?

The tool is complex with no output schema, and the description thoroughly covers return format (findings packet, citations, gaps, contradictions, hop), limitations, and performance expectations. Complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3; description adds useful context for question (broad/multi-part is fine, decomposition is the point) and depth (paid plan for thorough), though the schema already documents enum meanings.

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

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

Uses specific verbs and resource: 'Grounded multi-source research across Pipeworx's 1395 STRUCTURED data sources...' and clearly scopes it as a broad research tool, not open-web search. Distinguishes from siblings by naming ask_pipeworx for single lookups and current news.

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 ('Best for broad/multi-part questions') and when-not-to-use ('For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'). Also states the alternative if not signed in.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by specifying that results include full input schemas with curated examples and are ready to call directly, which tells the agent about the efficient output format.

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

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

The description is front-loaded with the key action and is well-structured. It includes a list of example domains which, while lengthy, is informative. It is appropriately concise 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?

Despite no output schema, the description explains the return format (top-N relevant tools with names, descriptions, schemas). Parameter count is high due to aliases, but the description handles this well. The tool is adequately documented for an agent to use effectively.

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 mentions the main parameter 'query' and its aliases, and provides examples of valid queries. While this adds context, it does not significantly exceed the schema's own 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 purpose: 'Find tools by describing the data or task.' It lists many example tasks and explains that it returns tool names, descriptions, and schemas, distinguishing it from sibling tools which are domain-specific.

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 advises 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear guidance on when to use, though it does not explicitly state when not to use.

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

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

Adds value beyond annotations: describes internal fan-out across sources, return structure (up to 5 filings with URIs, fundamentals sorted), notes USPTO sunset May 2025 with soft-fail, and GDELT→GNews fallback. Annotations only indicate readOnly/idempotent/open; description provides rich 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?

Front-loaded with trigger phrases and then systematically lists details. Slightly verbose with repeated statements, but efficiently packs much information. Slight trimming could improve 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 complexity, lack of output schema, and multiple data sources, description covers inputs, outputs, limitations (patents sunset), fallback behaviors, and return format. Fully equips agent to understand tool's capabilities and constraints.

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 already describes parameters well. Description adds context like zero-padded CIK requirement and that type only supports 'company', reinforcing usage nuances. However, some redundancy (names not supported appears twice). Baseline 3 raised to 4 for added clarification.

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 provides a full cross-source profile of US public companies, listing specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and return fields. Distinguishes itself from siblings like resolve_entity (needed for names) and compare_entities.

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

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

Explicit use cases given ('Tell me about X', 'research Acme') and instruction to 'ALWAYS PREFER over chaining single-pack... lookups'. Also states when not to use: if only have a name, use resolve_entity first.

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 confirms destructive behavior (delete), consistent with annotations (destructiveHint=true). Does not add new behavioral details 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, no redundancy, front-loaded with action, efficient.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and 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 coverage is 100% and parameter 'key' is well-described. The description adds no extra 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 states the action ('Delete a previously stored memory by key') and distinguishes it from siblings like 'remember' and 'recall'.

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 (stale context, task done, clear sensitive data) and mentions pairing with related tools, though no explicit when-not-to-use.

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

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

Annotations already provide readOnlyHint and idempotentHint. Description adds valuable behavioral context: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' – disclosing the process and output format.

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 plus a bullet list of use cases. Front-loaded with the main action. Could be slightly tighter, but no wasted words. Well-structured.

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

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

Given the low complexity (2 params, no output schema, rich annotations), the description covers purpose, usage, output format, and concrete use cases. Lacks error handling details, but sufficient for the tool's simplicity.

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

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

Input schema has 100% description coverage, so baseline 3. Description mentions URL usage ('for any URL') but doesn't add detail about max_links beyond schema. Schema already describes both params adequately.

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 'Generate a production-ready llms.txt file for any URL' – a specific verb and resource. The description distinguishes from related siblings like ai_visibility_check by focusing solely on llms.txt generation.

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 lists use cases (getting client site indexed, drafting own project, auditing competitor). Lacks explicit when-not-to-use or alternatives, but the specialized purpose and sibling context make it 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety traits. Description adds return content details but no further behavioral traits beyond what annotations imply. 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?

Single sentence that front-loads the verb and resource, includes essential details, and contains no unnecessary words. Optimal 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?

With output schema present, description need not detail return structure. It notes returned fields. Parameters fully covered by schema and description. Annotations cover behavioral aspects. The tool is simple but all needed info is provided.

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 well-described. Description adds examples ('44-1', 'C-318') but these are already in schema examples. Baseline score of 3 is appropriate as description does not significantly augment 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 verb ('Fetch full detail') and resource ('Canadian Parliament bill'), specifies required inputs (session and bill number), and lists returned fields (title, sponsor, status, legislative history). This distinguishes it from sibling tools like list_bills or get_politician.

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?

Implies usage context (when a specific bill's details are needed) but does not explicitly state when not to use or name alternative tools. Given clear sibling distinctions, the guidance is adequate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so the safety profile is clear. The description adds value by specifying the returned fields (name, party, riding, etc.) and links to debate contributions, which are behavioral details 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 a single, well-structured sentence that front-loads the key action and lists return fields concisely. Every word earns its place.

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

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

Given the low complexity (one required param, good annotations, output schema exists), the description sufficiently covers functionality. It lists return fields and source, though it could mention potential errors or case sensitivity. Still, it is complete enough for the scenario.

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

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

The only parameter is 'slug' with schema description 'Politician slug', and schema description coverage is 100%. The description reiterates 'by politician slug' but does not add new semantic meaning or format details 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 fetches a Canadian MP profile by slug from OpenParliament.ca, listing specific return fields. This distinguishes it from list_politicians (list) and get_bill (different 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?

It specifies the tool is used with a politician slug, implying single-entity lookup. While it doesn't explicitly contrast with siblings like list_politicians, the context is clear enough for an agent to decide when 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?

The annotations (readOnlyHint, idempotentHint, destructiveHint) already cover safety and idempotency. However, the description does not mention pagination behavior despite the presence of limit and offset parameters in the schema. It also omits details about data freshness or rate limits. Given the annotations, the bar is lower, but the lack of pagination clarification is a notable gap.

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

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

The description is two sentences long, clear, and front-loaded with the key information. It provides necessary details without extraneous content. Could be slightly more concise by omitting 'from OpenParliament.ca' if that is redundant, but overall efficient.

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

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

The tool has 5 parameters (0 required), an output schema, and annotations covering safety. The description explains filters and return fields but misses pagination and status value constraints. With the output schema handling return values, the description is moderately complete but lacks some behavioral context.

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

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

Schema description coverage is 40% (only session and sponsor have descriptions). The description adds meaning by listing the filterable parameters (session, sponsor, status) and what they do, but does not explain limit and offset or enumerate possible status values. It partially compensates for the low schema coverage but not fully.

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 'List', the resource 'Canadian Parliament bills', and the source 'OpenParliament.ca'. It specifies optional filters (parliament-session, sponsor, status) and the return fields (bill number, name, sponsor, status), making it easy to understand what the tool does. It distinguishes from siblings like get_bill (which likely retrieves a single bill) by being a list operation.

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

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

The description mentions optional filters but does not explicitly state when to use this tool versus alternatives like get_bill or search_debates. The usage context is implied (for listing bills with filters) but lacks explicit guidance on exclusions or when not to use it.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, informing the agent of safety and non-destructiveness. The description adds that results include witnesses and evidence, but does not disclose pagination, rate limits, or ordering behavior.

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

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

The description is very short (one sentence) and front-loaded with the key point. It is acceptably concise but could include more useful detail without becoming verbose.

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

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

The description lacks usage guidelines and parameter explanations. Although the output schema exists to cover return values, the overall context for a simple list tool is minimal and leaves gaps for an agent.

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

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

Schema coverage is only 25% (only committee_slug has a description). The description does not explain any parameters, leaving the agent to infer meaning from examples. No additional semantic context 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 title 'List Committee Meetings' clearly states the action and resource. The description adds 'with witnesses + evidence,' distinguishing it from sibling tools like list_committees, which list committees themselves. However, it could be more explicit about the verb.

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 guidance on when to use this tool versus alternatives like list_committees or search_debates. The context only implies usage when committee meetings with witnesses/evidence are needed, but no exclusions or prerequisites are mentioned.

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 destructive actions. The description adds context about the data source (OpenParliament.ca) and return fields, but doesn't disclose additional behavioral traits like rate limits or data freshness.

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

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

Two sentences with no redundant information. First sentence states purpose and filter, second sentence specifies return fields and intended use. Every word 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 presence of output schema and comprehensive annotations, the description is mostly complete. It explains source, return fields, and linkage to sibling. However, it lacks details on pagination and session format.

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 0% with three parameters (limit, offset, session). The description only mentions session as optional filter; limit and offset are not explained, leaving pagination behavior unclear.

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 lists Canadian House of Commons committees, specifying the verb 'List' and the resource 'committees'. It also differentiates from siblings by mentioning the output is for use with list_committee_meetings.

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

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

The description implies usage when you need committee slugs for meetings, but it does not explicitly state when to avoid this tool or contrast with sibling list tools like list_politicians. Guidance is present but not directive.

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, covering safety and mutability. The description adds that it returns 'current + historic' MPs, which is a useful behavioral detail not in annotations. It 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?

The description is a single short sentence, highly concise with no redundant information. However, it may be too terse—it does not elaborate on important aspects like pagination or default filters. It earns its place by stating the core function but could be slightly more informative.

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 presence of 6 optional parameters and an output schema, the description does not explain pagination (limit, offset) or default filtering behavior. It is minimally complete but lacks details that would help an agent use the tool effectively without relying on the schema alone.

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 67%; some parameters (limit, offset) lack descriptions. The description does not explain parameters beyond what the schema provides. For parameters with descriptions (name, party, current, province), the tool description adds no extra meaning, so the baseline score of 3 applies.

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

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

The description 'Current + historic MPs' clearly indicates the resource (MPs) and scope (current and historic), distinguishing it from single-item tools like get_politician and other listing tools. However, it omits an explicit verb like 'list', relying on the tool name, which slightly reduces clarity.

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 guidance is provided on when to use this tool versus alternatives such as get_politician, search_debates, or list_bills. The description lacks any context for when this tool is appropriate or when to prefer other tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description does not need to repeat that. It adds minor context (scope to caller, return fields) but not substantial behavioral traits 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 with no extraneous content: first sentence states purpose and return fields, second provides usage guidance. Highly efficient.

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

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

For a simple list tool with one optional parameter, the description covers purpose, return fields, and usage context. No output schema is present, but the enumerated return fields suffice. Annotations cover behavioral aspects.

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

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

Schema coverage is 100% and the schema already describes the single optional parameter. The tool description does not add any additional parameter information, so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' and enumerates the return fields (id, type, params, etc.). It is specific and 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?

It explicitly advises 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear context for when to use this tool versus its siblings.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that it returns vote data, but does not disclose rate limits, pagination behavior, or any other side effects. With annotations covering safety, the description provides 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?

The description is a single sentence that efficiently front-loads the tool's purpose, source, optional filter, and return data. Every word 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?

The description covers the core functionality and return fields with an output schema present. It lacks explicit handling of pagination (limit/offset) but is otherwise complete for a low-complexity list tool.

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

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

The description explains the 'session' parameter's purpose ('optionally filtered by session') but does not clarify 'limit' or 'offset', which are standard pagination parameters. Given the schema has 0% description coverage, the description partially compensates for session but not for the other two.

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

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

The description uses a specific verb ('List'), identifies the resource ('recorded votes in the Canadian Parliament'), names the data source ('OpenParliament.ca'), and describes the optional filter and return fields. This clearly distinguishes it from sibling tools like 'list_bills' or 'list_committees'.

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 the optional 'session' filter but does not provide guidance on when to use this tool versus alternatives (e.g., when to list votes vs. bills). No exclusions or prerequisites are mentioned.

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 (which provide no safety hints), the description discloses behavioral traits: 'The team reads digests daily and signal directly affects roadmap. Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.' This adds valuable context about impact and constraints.

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 states core purpose, second lists use cases, third provides critical constraints (rate limit, quota). Each sentence adds unique value, front-loaded with the imperative. No superfluous content.

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

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

For a simple feedback tool with 3 parameters (all well-documented in schema), the description fully covers purpose, usage, parameter best practices, and behavioral notes. No output schema exists, but return structure is not critical for a one-way submission. The description is complete 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 has 100% description coverage, providing detailed enum values and field meanings. The description adds extra semantic guidance: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This helps the agent craft appropriate messages, going beyond schema basics.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the action (tell) and resource (team), and distinguishes among feedback types (bug, feature, data_gap, praise). This differentiates it from sibling tools, which are query/action oriented.

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 when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also advises against pasting end-user prompts and notes rate limits and cost. No sibling tool covers feedback, so when-not is implicit.

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 adds that data is derived from CF analytics-engine, contains no PII, and is cached for 5min-1h depending on window. This provides valuable behavioral context not captured by annotations.

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

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

The description is concise with three sentences plus a bulleted list of use cases. Every sentence adds value, and the purpose is front-loaded. No unnecessary 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 simplicity (one optional parameter, no output schema, rich annotations), the description fully covers purpose, use cases, data source, caching behavior, and privacy. Nothing essential is missing.

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

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

The single parameter 'window' is fully described in the schema with enum values and a description. The tool description adds no additional semantic meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'returns' and the resource: 'top tools, top packs, and total call volume' over a defined window. It distinguishes itself from sibling tools by focusing on aggregated trending data from other AI agents, which is unique among the listed 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?

Three explicit use cases are provided (discovering hot data sources, confirming canonical choice, checking alignment). While it does not specify when not to use the tool or name alternative tools, the use cases are clear and context-rich.

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

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

Despite annotations already declaring readOnlyHint and idempotentHint, the description adds substantial behavioral context: internal checks (Jaccard similarity threshold, placeholder filter), fill check against live CLOB, and the meaning of realizable_edge_pp. This far exceeds 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 thorough but lengthy and dense, making it less concise. While well-structured with clear sections, it could be trimmed for quicker parsing by an AI agent.

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

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

The description fully covers all modes, constraints, response fields, and fill check logic. Given the complexity and lack of output schema, it provides enough detail for correct invocation and interpretation.

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

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

Schema coverage is 100% for both parameters, but the description adds critical context: event accepts full URLs, topic is a seed question, and explains the internal processing for each mode. This adds significant 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 states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and contrasts with sibling tools like polymarket_fill_risk.

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 guidance: 'Call with NO args for trending_scan... pass event for... or topic for...' Recommends event mode for specific markets and explains when not to trade (realizable_edge_pp ≤ 0). References polymarket_fill_risk for custom sizing.

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, etc.), the description adds rich behavioral context: caching at KV level with knob-keying, detailed model families, tradeable-edge knobs, response structure including diagnostics, and edge calculation details. 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 very long and dense, combining model internals, response structure, and parameter guidance. While well-structured into segments, it is not concise and may overwhelm an agent with extraneous detail.

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

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

Given no output schema, the description compensates by detailing the response structure (by_segment, fed_candidates, _diagnostics) and edge fields (edge_pp_net, kelly_fraction, etc.). It covers most aspects but omits explicit listing of all response fields.

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 tool description adds extra context for several parameters (e.g., min_liquidity, max_spread_pp, min_partition_leg_kelly) explaining their purpose in the edge pipeline, going 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 scans markets and returns edge opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan' and resource 'Polymarket markets', but does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 frames the tool for 'what should I bet on today' and notes agents can discover opportunities without paging hundreds of markets. However, it does not provide guidance on when not to use it or alternatives.

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

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

The description adds substantial detail beyond annotations: decay numbers from daily closes net of default slippage, not intraday; explanation of edge_pp_net being signed; details on snapshot gaps and expiration. Annotations already declare readOnly, idempotent, openWorld, and non-destructive. 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 well-structured: a concise one-sentence summary at the top, followed by detailed breakdown of response fields and limitations. While it is moderately long, every sentence provides necessary context and avoids repetition. It front-loads the purpose.

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

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

Given no output schema, the description thoroughly explains the response format (tracked with time-series, trend, decay; expired with lifespan; snapshot_dates). It also covers limitations (60-day TTL, snapshot gaps, no intraday). This is sufficient for an agent to understand tool behavior and usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining 'window' as snapshot family with examples (24hr, 1wk, 1mo) and default, and 'days' as lookback with clamp range (2-30). It also ties parameters to the response structure (e.g., window affects which snapshots are 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 explicitly states it provides edge persistence and decay telemetry from daily polymarket_edges snapshots, answering the core question of edge age and shrinkage. It distinguishes between fresh and old edges, and clearly outlines the response structure with tracked, expired, and snapshot_dates arrays, making it distinct from siblings like polymarket_edges.

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

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

The description explains when to use the tool: to analyze edge history and decay, and for assessing whether an edge is fresh or aged. It implies that polymarket_edges is for current edges. It also provides limits (60-day TTL, no intraday) and explains the significance of expired opportunities. However, it does not explicitly list alternatives or when not to use it.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds rich behavioral context: walks the order book ladder, returns verdicts like 'clean|degraded|cannot_fill', warns about 'thin_legs' and 'forced_directional_risk'. 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 quite long but densely packed with necessary information. It uses clear structure with bold headers (SINGLE-MARKET, BASKET) and front-loads the main purpose. A minor deduction for verbosity, 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 complexity (two modes, no output schema), the description explains return values in detail for both modes, including specific fields and risk indicators. It also contextualizes the tool's importance in real arb-bot P&L. Complete enough 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%, but the description adds significant meaning: explains the two modes, default behavior for 'side' (auto in basket), interpretation of 'size_usd' differently for single-market vs basket, and clamps. This greatly enriches parameter understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two distinct modes (single-market and basket) and explicitly distinguishes from siblings by advising use before acting on polymarket_arbitrage or polymarket_edges signals, making it sharply differentiated.

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 explains the risks of partial fills and unhedged positions, though it could be slightly more explicit about when not to use or alternatives, but the 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?

Annotations already declare readOnly/openWorld/idempotent. Description adds extensive behavioral context: two modes, response structure with safety fields (compatibility_warning, temporal_alignment), counters for dropped comparisons, and explanation of when spreads are meaningless. 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?

Description is lengthy but well-structured with clear sections and bold labels. Information-dense with no filler, though could be slightly more streamlined. 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 no output schema, the description fully documents return fields (spreads, compatibility_warning, temporal_alignment, counters) and edge cases. Covers all relevant operational details for an agent to use correctly.

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

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

Schema coverage is 100%, but description adds value by listing the exact pre-mapped topic values, explaining override behavior, and giving examples. Provides more context than schema alone.

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

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

The description clearly states it calculates cross-venue spreads between Kalshi and Polymarket for the same outcome, specifying two modes (topic shortcuts and explicit tickers) and distinguishing it from sibling polymarket tools like arbitrage and edges.

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

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

Provides explicit guidance on when to use topic vs explicit modes, warns that pre-mapped topics often yield compatibility warnings, and explains that real spreads are rarer than the shortcut list suggests. Includes when-not-to-use conditions like temporal misalignment.

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 safe, idempotent, read-only operation. The description adds behavioral details: scoping by identifier (anonymous IP, BYO key hash, or account ID) and the effect of omitting the key (listing all keys). 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 three sentences, front-loaded with the primary action, and contains no fluff. Each sentence provides essential information about purpose, usage, and pairing.

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 simplicity (one optional parameter, no output schema), the description adequately covers input behavior, scoping, and sibling tools. Output format is implied but not explicitly detailed, which is acceptable for such a straightforward tool.

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

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

The input schema has 100% coverage with a clear parameter description. The description reinforces behavior (omit key to list all) and provides semantic context about what the value represents (user's target ticker, etc.), adding marginal 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 retrieves a previously saved value via remember or lists all saved keys when the key argument is omitted. It explicitly names the related tools (remember, forget) for context, distinguishing it 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 explains when to use the tool: to look up previously stored context like tickers, addresses, or research notes, avoiding re-derivation. It also implicitly suggests using remember for saving and forget for deletion, and notes scoping by identifier.

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

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

The description adds behavioral details beyond annotations: it explains the mark_read parameter's effect on subsequent calls, the persistency of the feed, and the content of each alert. No contradiction with annotations (readOnlyHint true is consistent since marking read is a minor state change, not destructive).

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 (three sentences), front-loaded with purpose, and every sentence adds necessary information without redundancy.

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

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

Despite no output schema, the description covers return fields, all parameters, and usage patterns (polling, filter options). It is complete for a read-only, list-type tool with optional filters.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by giving concrete examples (e.g., type: 'sec_8k'), explaining the mark_read flag's behavior, and noting the since parameter's meaning, which enriches parameter understanding.

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

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

The description uses a specific verb ('Pull') and clearly identifies the resource ('fired events from your subscription feed'). It distinguishes the tool from siblings like 'list_subscriptions' by focusing on retrieving alert events, not managing 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?

The description explains filtering options and mentions that polling works fine, providing usage context. It also notes an alternative access method (GET endpoint) for scripts/dashboards, though it does not explicitly contrast 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?

Adds substantial context beyond annotations: fallback from GDELT to GNews, soft-fail for USPTO, return structure (changes grouped by source, total_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?

Single paragraph, front-loaded with examples, each phrase adds information. No redundant 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?

Despite no output schema, description details return format. Covers parameter descriptions, source behaviors, and fallback mechanisms. Complete for a tool of this complexity.

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

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

Schema coverage is 100%. Description adds value with usage examples (relative date shorthands, recommendation for '30d' or '1m', explanation of value 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?

Description clearly states the tool provides a change feed for a company over time, enumerating sources (SEC, GDELT/GNews, USPTO) and distinguishes from sibling entity_profile for static profiles.

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

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

Includes explicit example queries and recommends when to use entity_profile instead. Lacks explicit when-not-to-use or exclusions beyond that one sibling.

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 (idempotentHint=true), the description discloses scoping by identifier, persistence differences between authenticated and anonymous sessions (24-hour), and that memory is key-value. 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?

Five concise, front-loaded sentences with no superfluous information. Purpose, usage, and behavioral details are efficiently ordered.

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 write operation with no output schema, the description covers purpose, usage, behavioral details, memory scoping, and pairing with sibling tools, making it fully self-contained.

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

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

Schema coverage is 100% with descriptions for key and value. The description adds examples for key and clarifies value is any text, but this adds minimal value beyond the schema, meeting the baseline.

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

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

The description clearly defines the tool as saving data for reuse across conversations and sessions, with concrete examples of what to store (ticker, address, preference). It distinguishes from sibling tools recall and forget by naming them as partners.

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: when discovering something worth carrying forward. Names sibling tools recall and forget for retrieval and deletion, providing clear alternatives.

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

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

Annotations already declare safe, read-only, idempotent behavior. The description adds valuable behavioral details: internal cascading through multiple lookup endpoints, auto-disambiguation for company inputs, and return format specifics (ticker+CIK, RxCUI, citation URIs). 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?

Front-loaded with example queries, then structured into bullet points for entity types, each clear and self-contained. Every sentence provides unique information without redundancy.

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

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

Despite no output schema, the description thoroughly covers return values for both entity types, input flexibility, internal process, and integration with other tools via citation URIs. Completely equips the 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?

Input schema covers both parameters with full descriptions. The description adds practical context: auto-disambiguation, accepted input formats (ticker, CIK, name), and what is returned per type, augmenting the schema's structural details.

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 like 'resolve' and gives concrete query examples ('What's the ticker for...', 'find the CIK for...'), clearly stating its purpose to map user-spoken names to canonical identifiers. It distinguishes between entity types (company, drug) and details what each returns.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID', providing clear context for when to invoke. It explains that it replaces 2-3 manual lookups. While it doesn't explicitly list when NOT to use, the strong positive guidance suffices given sibling tools cover other tasks.

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 openWorldHint, which align with the description. The description adds that the tool internally probes entities with ai_visibility_check and ranks results, which is consistent. No contradictions or hidden behaviors are present.

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 and well-structured, with a front-loaded purpose statement, a specific use case, and a clear outline of the output. Every sentence adds value without repetition 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?

Given the tool's moderate complexity and the presence of annotations and full schema coverage, the description adequately explains the process and output. It mentions the ranked list with score, confidence, and signal density, though more detail on the output format could be beneficial.

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

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

The input schema has 100% coverage for parameter descriptions. The description adds behavioral context beyond the schema, such as treating the first entity as the 'subject' for narrative and mentioning the default model. This enhances understanding.

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

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

The description clearly states that the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check probes, and outputs a ranked list with scores. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the competitive audit context.

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 concrete use case ('does Claude know about us as well as our competitors?') and implies it is for competitive AI-marketing audits. However, it does not explicitly list when not to use the tool or mention alternatives like using ai_visibility_check for a single entity.

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

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

Annotations indicate readOnly, idempotent, and not destructive. Description adds critical context: partial failures (bundlephobia first measurement can take 5-30s), graceful degradation with sources_failed list, and detailed return data structure. 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?

Single paragraph but dense with information. Every sentence serves a purpose, though it could be slightly more structured (e.g., list of returned 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?

No output schema, so description fully explains return values: summary block fields, per-advisory detail, links, and alternative versions. Also covers partial failure behavior. Complete for a 2-param 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. Description adds value by explaining default version behavior and acceptance of scoped packages ('@types/node'). Not redundant with schema.

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

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

The description clearly states the tool's purpose: a composite check for npm packages combining deps.dev and bundlephobia data. It explicitly answers 'should I add this npm package' and distinguishes from siblings (none similar).

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 tells when to use: 'Use whenever an agent asks is X safe / popular / small'. Also provides exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds context about return fields and API limitations, but does not disclose any additional behavioral traits 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?

Three concise, front-loaded sentences. Each sentence adds value: purpose, limitation, and filter requirement. 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 6 parameters, no required params, 100% schema coverage, output schema presence, and comprehensive annotations, the description is complete. It explains what to do, what not to do, and includes examples in the 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%, but the description adds practical usage notes like date format, offset base, and how to obtain politician slugs via list_politicians, enhancing schema meaning.

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 lists Hansard speeches by MP and/or party, optionally filtered by date, and returns speaker, date, and text. It distinguishes from siblings like list_politicians.

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

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

Explicitly states the API has no free-text search and requires filtering by politician or party. Provides guidance on finding politician slugs via list_politicians.

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?

Adds significant behavioral context beyond annotations: uses BGE-base-en embeddings, cosine over 500-char windows, 200K char cap with truncation flag, and each passage includes offset for verification. 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?

Four sentences, no fluff. Front-loaded with purpose, followed by usage guidance, sibling pairing, and technical details. Every sentence earns its place.

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

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

Given the schema, annotations, and no output schema, the description covers what the output looks like (passages with offsets and scores), technical details (embedding model, windowing, truncation), and usage context. Fully sufficient for an AI agent.

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

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

Schema coverage is 100% with good property descriptions. The description adds extra value with query examples and context for the 'text' parameter, exceeding the 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 it performs 'Semantic search INSIDE a fetched record' and provides concrete examples (SEC 10-K, article). It distinguishes from the sibling tool ask_pipeworx_grounded by explaining how they pair together.

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 the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. Could be clearer on when not to use, but the guidance 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?

The description provides extensive behavioral details beyond annotations: requires OAuth account, delivery channel constraints (SMS cap, webhook auto-disable after 10 failures), phone verification, and the fact that subscriptions persist. No contradictions with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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?

Every sentence adds value. The description is well-organized: starts with purpose, then prerequisites, then types with examples, then delivery options. It is dense but not verbose, and key information is front-loaded.

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

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

Given the tool's complexity (3 parameters with nested objects, multiple subscription types, optional delivery channels), the description is remarkably complete. It covers authentication, type-specific parameters, delivery constraints, and return value. No output schema exists, but the description adequately explains what is returned.

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

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

Even with 100% schema coverage, the description adds substantial meaning: it provides concrete examples for each subscription type (e.g., sec_8k items, polymarket_edge topic), explains required vs optional fields, and clarifies delivery channel requirements (phone verification, SMS cap). This goes well 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 'Create' and resource 'proactive monitoring subscription', and clearly states it returns a subscription ID. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe, leaving no ambiguity about its function.

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

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

The description explains when to use the tool (proactive monitoring) and highlights prerequisites (Pipeworx OAuth account). However, it does not explicitly state when not to use it or provide alternatives, though the context is clear given sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond annotations: it explains that the tool returns example questions with exact tool and argument shapes, and that it draws from a live catalog. 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 thorough but slightly verbose. It front-loads the purpose with common queries, then lists categories and usage details. Every sentence earns its place, but some trimming could improve conciseness while retaining clarity.

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

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

For a tool with one optional parameter and no output schema, the description is sufficiently complete. It explains what is returned (category-bucketed questions with tool shapes) and lists the categories. The context of being an onboarding tool is clearly established.

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 substantial meaning: it explains that the topic parameter is optional, lists all valid values (finance, pharma, etc.), and describes behavior when omitted (cross-category spread). This goes well beyond the schema's brief description.

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

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

The description uses a specific verb ('returns') and resource ('category-bucketed example questions'), clearly differentiating it from sibling tools by stating it is the 'onboarding entry point'. It also lists numerous alternative phrasings for the query, making the purpose unmistakable.

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

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

The description explicitly states when to use this tool: '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 provides guidance on optional argument usage (topic) and implies when not to use (if already familiar).

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 include destructiveHint=false and idempotentHint=true. The description adds valuable behavioral context: ownership enforcement, deactivation (not deletion), and preservation of historical events via recent_alerts. This goes beyond the annotations.

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

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

Two concise sentences front-load the purpose and add necessary details without any 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 tool with one parameter and no output schema, the description covers the essential: purpose, ownership constraint, and the side effect of deactivation versus deletion. It is complete.

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

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

The schema already has 100% coverage for the single parameter 'id', describing it as a uuid returned by subscribe. The description adds minimal extra context beyond the schema.

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

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

The description states 'Cancel a subscription by id' which provides a specific verb and resource. It clearly distinguishes from sibling tools like 'subscribe' and '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?

The description notes ownership enforcement ('you can only cancel your own subscriptions'), indicating when to use and providing a clear usage constraint. It explains the effect (deactivation vs deletion) but does not explicitly mention 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?

The description detailes the two pipelines (SEC EDGAR for financial, grounded for other claims), the return values (verdict, actual value with citation, reasoning), and tolerance behavior. This adds significant context beyond the annotations (readOnlyHint, openWorldHint, etc.), which are already informative. 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 well-structured, front-loading trigger phrases and purpose. While it is somewhat lengthy, every sentence adds unique information (pipelines, verdicts, citation). Minor redundancy could be trimmed, but overall efficient 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?

For a tool with two parameters, no output schema, and complex behavior (two pipelines, multiple verdicts), the description covers all critical aspects: claim types, pipelines, verdict values, citation format, and reasoning. It leaves no major gaps for an agent to understand what the tool does and 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 coverage is 100%, so baseline is 3. The description adds value by explaining the tolerance_pct defaults (implied by wording, capped at 5) and a use case (hallucination detection with 1–2%). This goes beyond the schema's basic description.

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

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

The description clearly states the tool verifies natural-language factual claims against authoritative sources, provides trigger phrases ('Is it true that…', 'fact check'), and distinguishes between financial claims (SEC EDGAR + XBRL) and other claims (grounded pipeline). This specificity differentiates it 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies that it replaces 4–6 sequential calls, implying efficiency. However, it does not explicitly mention when not to use it versus similar siblings like ask_pipeworx_grounded, though the claim-specific focus is clear.

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