Legiscan

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

Annotations (readOnlyHint, idempotentHint) are already transparent about read-only, idempotent behavior. The description adds value by detailing return format (per-model score, confidence, signals, raw_response + combined view) and cost implications (free vs BYO key). 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?

Two well-structured sentences, front-loaded with purpose, followed by return details. Every sentence serves a purpose with 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 tool complexity (4 optional params, no output schema), the description covers return format, default model, and key usage scenarios. Lacks scoring methodology details but is sufficient for standard use with open-world hint.

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 4 parameters. The description supplements by clarifying default model behavior, when _apiKey is needed, and how 'context' disambiguates. This adds meaningful guidance 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 ('probe') and names the resource ('LLMs') and output ('score visibility 0-100'). It clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on visibility scoring per model for marketing audits.

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 (AI-marketing audits, pre-launch brand checks, competitive monitoring) and how (default free model, optional paid Anthropic via _apiKey). It provides clear context but lacks explicit when-not-to-use or direct alternatives among siblings.

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

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

Annotations already declare read-only and idempotent behavior. The description adds valuable context: it routes to thousands of tools, fills arguments, and returns structured answers with citation URIs. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with a key directive. It efficiently conveys purpose, usage, and examples without redundancy. Every sentence adds value, maintaining conciseness.

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

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

Given the tool's complexity (meta-tool routing to many sources) and absence of output schema, the description adequately explains what it does and what it returns (structured answers with citations). It lacks exact output format but provides enough context for an agent to understand expected results.

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 six alias parameters. The description does not add new semantic meaning beyond stating 'Your question or request in natural language.' While it provides examples, the parameter semantics remain at baseline.

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

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

The description clearly states the tool's purpose: to answer factual questions using authoritative structured data from many sources, contrasting with web search. It specifies domains (SEC, FDA, etc.) and gives examples, making the purpose unmistakable and 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 explicitly advises preferring this tool over web search for a wide range of factual queries and lists example questions. It implies when to use but does not explicitly state when not to use, which slightly limits guidance. However, it provides strong positive usage context.

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, etc. The description adds valuable behavioral context: the refusal mechanism with specific reasons (not_in_source, no_tool_match, etc.), the return format with fields like answer and evidence, and the extra LLM call cost. This goes well beyond annotations.

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

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

Concise yet comprehensive: front-loaded with the main purpose, followed by details on routing, return format, refusal reasons, and usage guidance. Every sentence adds value with no wasted words.

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

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

For a complex tool with no output schema, the description fully explains return values (answer, evidence, confidence, etc.) and refusal reasons. It also contrasts with the sibling tool and notes the cost trade-off. Complete given the tool's complexity and available structured data.

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

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

Schema description coverage is 100% with clear definitions for each parameter (including aliases). The description mentions 'question' but adds no additional semantic meaning beyond what the schema already provides. 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 it's a 'hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers only from tool results. It distinguishes itself from the sibling tool 'ask_pipeworx' by noting the extra LLM call cost and appropriate use cases.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also says when not to: 'prefer ask_pipeworx for casual lookups.' This provides clear context and 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 readOnlyHint=true and idempotentHint=true, so the description doesn't need to reiterate safety. The description adds extensive behavioral context: fan-out logic, resolver contract, parent-event extraction, news fallback handling, safety short-circuits (low_confidence_match, market_closed_or_inactive), illiquidity notes, and resolution-rule risk. This goes far beyond what annotations provide, making the tool's behavior fully 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?

The description is long but well-structured. It starts with the core purpose, then systematically covers classifiers, fan-out examples, response shapes, resolver contract, edge cases, and safety. While dense, every section adds unique information. Slightly verbose, but appropriate for the tool's complexity.

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

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

Given no output schema, the description thoroughly explains all aspects of the return value: result.market fields, result.analysis with model probability/edge/24h-warning, result.evidence structure, market_match_confidence and alternatives, parent_event extraction, news fields with fallback status, and blocking mechanisms for low-confidence/dead markets. It also covers resolution-rule risk and illiquidity. This completely covers what an agent needs to correctly interpret the tool's output.

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 three parameters (market, depth, include_raw). The description adds value by explaining how the market parameter is resolved, what 'quick' vs 'thorough' depth entails, and the difference between raw and summarized include_raw. Examples further clarify usage. This enhances understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text), output (evidence packet + comparison), and use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). This distinguishes it from siblings like polymarket_edges or ask_pipeworx by focusing on a single bet research.

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

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

The description explicitly tells when to use this tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also implies when not to use it by describing safety shortcuts (e.g., low-confidence resolution, closed markets). However, it does not explicitly mention alternative tools for related tasks (e.g., polymarket_edges for multiple bets), but context is clear enough for an AI 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 indicate readOnly, openWorld, idempotent, and non-destructive. Description adds specifics: uses SEC EDGAR/XBRL for companies, handles off-calendar fiscal years, returns paired data with citation URIs, and sorts results by primary metric. No contradictions.

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

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

The description is a single dense paragraph but front-loads purpose with examples. Every sentence adds value. Could be slightly more structured, but overall concise without 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 no output schema, the description explains returns (paired data + citation URIs) and covers both entity types. Sorting behavior is mentioned. Sufficient for agent understanding, though more detail on output format could improve completeness.

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. Description adds value by clarifying parameter usage with examples (e.g., 'For company: 2–5 tickers/CIKs...') and notes that results are sorted by primary metric. Schema already covers type enum and array constraints.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs. It specifies what data is pulled for each type (financials for companies, adverse-event counts for drugs) and distinguishes from sequential lookups.

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 tool provides explicit usage guidelines: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also gives trigger phrases and states it replaces 8-15 sequential lookups, aiding agent decision-making.

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?

Describes return format (findings packet with evidence, confidence, source, citations, gaps), expected duration (15-60s), and that it never invents facts. Annotations already indicate readOnly and idempotent, but description adds rich behavioral context without contradiction.

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

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

Description is comprehensive but somewhat lengthy; however, every sentence adds value. Front-loaded with key benefit. Could be slightly more concise but still 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 tool's complexity and lack of output schema, the description fully covers what the tool does, its output format, prerequisites, and alternatives. No gaps remain for an agent to understand 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% but description adds meaning: explains depth values (quick=3, standard=5, thorough=8) and that thorough requires paid plan. Question parameter is described as natural language and broad/multi-part.

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

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

The description clearly states the tool performs grounded multi-source research by decomposing questions into sub-questions, routing to tools in parallel, and extracting answers with citations. It distinguishes from sibling 'ask_pipeworx' which is for single lookups.

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 to use for broad/multi-part questions and contrasts with ask_pipeworx for single lookups. Also notes account requirements and paid plan for 'thorough' depth.

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 that the tool returns top-N results with full schemas and curated examples, that results are ready to call directly without a second schema lookup, and that it returns the most relevant tools. 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 front-loaded with the main purpose. It lists many example domains which adds value but slightly reduces conciseness. Each sentence contributes useful information.

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

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

Given no output schema, the description explains what is returned: 'names, descriptions, and full input schemas (with curated examples)'. It also gives a clear usage pattern. The tool is complex (many parameters, siblings), but the description is thorough 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. The description adds value by explaining that the query parameter accepts natural language descriptions and lists aliases. It also specifies the default and max for limit. This goes 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 tools by describing data or task, lists many example domains, and explicitly distinguishes itself by stating 'Call this FIRST when you have many tools' and 'returns the top-N most relevant tools with names, descriptions, and full input schemas'. This differentiates it from sibling tools which are specific-purpose 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?

Explicit usage guidance is given: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set'. This tells the agent when to use this tool before others.

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 behavioral details beyond annotations: fans out across SEC, XBRL, USPTO, news, GLEIF; notes USPTO sunset soft-fail and GDELT→GNews fallback. 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?

Packs a lot of information but is well-organized with examples and a structured list of return data. Slightly verbose but each 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?

For a complex multi-source tool, the description covers purpose, input requirements, output fields, and behavioral notes (fallbacks, limitations). Annotations cover safety. No output schema, but return info is described.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining type is only 'company' and value must be ticker or zero-padded CIK, and names not supported, going 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 the tool provides a full cross-source profile of US public companies with example queries and specific data returned. It distinguishes from sibling tools that do single-pack lookups.

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 to prefer this over chaining single-pack lookups for holistic views, and instructs to use resolve_entity first if only have a name. Provides clear when-to-use and alternatives.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true, so the description's mention of deletion is consistent. It adds context about clearing sensitive data but does not disclose further behavioral traits beyond what annotations already 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?

Two sentences, no waste, front-loaded with the core action. Every sentence adds value.

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

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

Given the simple input schema (single string) and no output schema, the description covers the essential purpose and use cases. It is sufficient for an agent to understand when and how to use the tool.

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

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

Schema coverage is 100% and the parameter description is clear. The tool description repeats the concept of 'by key' but does not add new parameter-specific meaning beyond what the schema already provides.

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

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

The description clearly states the action ('Delete') and the resource ('previously stored memory by key'), with a specific verb and noun. It distinguishes from sibling tools like 'remember' and 'recall' by focusing on deletion.

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

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

The description provides explicit use cases ('context is stale, task is done, clear sensitive data') and mentions pairing with 'remember' and 'recall'. However, it does not explicitly state when not to use it or provide alternative 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 indicate safety (readOnlyHint, idempotentHint, no destruction). The description adds valuable behavioral details: fetching the page, extracting title/description/key links, and outputting standard llms.txt markdown. 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, each serving a clear purpose: purpose, process, and use cases. No filler or redundant information.

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

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

Given the tool's simplicity (2 params, no output schema) and rich annotations, the description covers the output format, use cases, and process comprehensively. No gaps remain.

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

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

Schema coverage is 100% with descriptions for both parameters. The description doesn't add new meaning beyond what the schema says (e.g., 'max_links' default/max already documented). Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: generate a production-ready llms.txt file for any URL. It specifies the target AI crawlers, the actions taken (fetches, extracts, emits), and the output format. This differentiates it from sibling tools like 'scan_competitor_ai_presence'.

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

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

The description provides explicit use cases such as getting a client's site indexed, drafting llms.txt, or auditing competitors. While it doesn't mention when not to use it, the context makes the intended usage 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, idempotentHint, and openWorldHint, covering safety and idempotency. The description adds value by specifying the content of the response (status, sponsors, subjects, links) and noting the optional _apiKey parameter. 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 extremely concise: two sentences and an example. The first sentence fronts the core purpose, and the example immediately demonstrates usage. No wasted words.

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

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

Given the low complexity of a single-bill retrieval tool and the presence of comprehensive annotations, the description adequately covers what the tool does and how to use it. It lists key response fields. Without an output schema, additional details about the exact structure might be beneficial, but the description is sufficient for a read-only, idempotent operation.

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 both parameters. The description enhances this by providing a concrete example and clarifying that bill_id comes from search_bills, and that _apiKey is optional for higher limits. This adds useful 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 clearly states it retrieves full details for a single US bill, listing specific fields (status, sponsors with subfields, subjects, links). It distinguishes itself from the sibling 'search_bills' by specifying that the bill_id comes from that tool, fulfilling the 'specific verb+resource+scope' criterion.

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

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

The description explicitly instructs to use the bill_id obtained from search_bills and provides a usage example. While it doesn't state when NOT to use it, the context is clear enough for typical scenarios. No explicit alternatives are mentioned, but the sibling list provides context.

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, providing a strong baseline. The description adds little behavioral context beyond confirming it lists sessions, and does not disclose any hidden traits or side effects.

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 extremely concise with two sentences and an example. It front-loads the action and provides essential information 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?

Given the tool's simplicity (2 parameters, no output schema) and rich annotations, the description is complete. It covers the purpose, output fields, usage context, and includes an example, leaving no gaps.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('state' and '_apiKey'). The description does not add any new meaning beyond what the schema provides, resulting in a baseline score 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 lists legislative sessions with specific output fields (start/end years, session IDs). While it doesn't explicitly distinguish from sibling tools, the verb 'list' and resource 'sessions' make the purpose distinct among the given 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 phrase 'Useful to scope which session to track bills in' provides clear context for when to use this tool. However, it does not explicitly state when not to use it or mention alternatives, which prevents a higher score.

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 safety/hints (readOnly, idempotent, not destructive). Description adds return field details and defaults, enhancing transparency.

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

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

Two sentences, no wasted words, front-loaded with purpose. 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?

No output schema, but description lists all returned fields and explains default behavior. Complete for a simple 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?

Schema already fully describes the single parameter include_inactive (100% coverage). Description adds no extra parameter information.

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 (List), resource (subscriptions), and scope (caller's active). It distinguishes from siblings like subscribe/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?

Explicitly says when to use: to review monitoring before adding or to find an id to cancel. Does not mention alternatives but sufficient context.

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 provide neutral hints, but the description adds critical behavioral context: rate limit of 5 per identifier per day, free usage not counting against tool-call quota, and that the team reads digests daily affecting roadmap.

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 paragraph that front-loads the purpose and then provides usage guidelines and behavioral notes. Every sentence adds useful 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?

The tool has no output schema, but the description explains the outcome (team reads digests, impacts roadmap) and covers limitations (rate limit, quota). For a feedback tool with 3 parameters, this provides complete context for an agent to use it correctly.

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

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

Schema coverage is 100% with good descriptions. The description further clarifies the meaning of enum values for type and explains the optional context object, adding value beyond the schema. However, the schema already provides clear definitions, so a 4 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 tool is for sending feedback to the Pipeworx team about bugs, features, data gaps, or praise. It distinguishes itself from sibling tools like ask_pipeworx, which are for querying, not providing feedback.

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 for each feedback type (bug, feature, data_gap, praise) and provides clear instructions on what to include (describe in terms of tools/packs, avoid user prompts). Also mentions rate limits and quota-free usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: data is self-aggregating from CF analytics-engine, no PII, and caching behavior (5min-1h). No contradictions with annotations.

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

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

The description is concise, well-structured, and front-loaded with the core purpose. Every sentence adds value: purpose, use cases, data source, privacy, caching. There is no redundant or wasted text.

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 covers purpose, use cases, data provenance, privacy, and caching. It is fully complete for effective agent invocation.

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

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

Schema description coverage is 100% and already explains the 'window' parameter with enum values and meaning. The description adds a brief note on window tradeoffs but does not add substantial new meaning beyond the schema. Baseline 3 is appropriate since schema already does the work.

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 'Returns the top tools, top packs, and total call volume over a recent window.' It uses a specific verb (returns) and identifies the resource (trending data). The differentiation from sibling tools is implicit through the use cases, making it clear what this tool uniquely provides.

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 three explicit use cases: discovering hot data sources, confirming canonical tool choice, and seeing use case alignment. It also explains window tradeoffs. However, it does not explicitly mention when not to use this tool or name alternatives. Overall, it gives strong guidance for appropriate invocation.

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 provide readOnlyHint, openWorldHint, idempotentHint. Description adds critical behavioral details: fill check referencing `polymarket_fill_risk`, semantic anchor (Jaccard similarity), partition filter (placeholder slugs), and response structure. No contradictions.

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

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

Well-structured with labeled sections, but somewhat verbose. Every sentence adds value, but minor redundancy could be trimmed. Still highly effective.

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

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

Covers all aspects: modes, parameters, error conditions, response fields, fill check reference. Without output schema, description provides sufficient detail about return values and trade execution criteria.

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 parameter descriptions. Description adds meaning: explains slug format, topic as seed question, how each triggers a mode, and error condition if no args. Complements the schema effectively.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, distinguishing between `event` and `topic` modes. This differentiates it from sibling tools like `polymarket_fill_risk` and `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?

Explicitly requires one of `event` or `topic`, and explains when to use each mode. Provides recommendations (`event` for specific market, `topic` for cross-event scanning) and warns against trading when realizable edge is non-positive.

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

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

The description discloses extensive behavioral traits: it returns opportunities by three segments (model_driven, structural_arbitrage, concentrated_longshot) with detailed methodology, caching at 1h KV level, diagnostics for empty segments, and edge fields like edge_pp_net, kelly_fraction, etc. This far exceeds the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) and does not contradict 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 thorough but verbose, containing detailed formulas and thresholds that could be condensed. It is well-structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and front-loads the purpose, but the length may slow AI parsing. Some extraneous details (e.g., specific α values) could be omitted or simplified.

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 of 9 parameters, no output schema, and nested segments, the description is remarkably complete. It explains the return structure (by_segment, fed_candidates, diagnostics), edge fields, tradeable-edge knobs, and caching behavior. Without an output schema, the description fully informs an agent of what to expect.

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

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

All 9 parameters have descriptions in the input schema (100% coverage), achieving baseline 3. The description adds extra context beyond schema, such as explaining slippage assumption (zero fees but bid/ask), tradeable-edge knobs as filters, and the meaning of min_partition_leg_kelly for partitions. This additional value justifies a 4.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. The title 'Polymarket Edges' and the opening line 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' specify the verb, resource, and unique value proposition, distinguishing it from siblings like polymarket_arbitrage or polymarket_kalshi_spread.

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 it's built for 'what should I bet on today' and that agents discover opportunities without paging hundreds of markets. It provides guidance on when to use tradeable-edge knobs (min_liquidity, max_spread_pp) and mentions default parameters. However, it does not explicitly contrast with sibling tools or give when-not-to-use scenarios, but the context is clear 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 indicate read-only, open-world, idempotent, non-destructive. Description adds details on data source (daily snapshots with 60-day TTL), response structure (tracked, expired, snapshot_dates), and computation (decay from daily closes, not intraday). 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?

Description is detailed but well-organized with sections (ARGUMENTS, RESPONSE, LIMITS). A bit lengthy but every sentence adds value; minor conciseness improvement possible.

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 two optional parameters and no output schema, the description thoroughly explains the return structure (tracked array with time-series, trend, decay; expired with lifespan; snapshot dates) and limitations (TTL, start date, daily close basis). 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?

Input schema has 100% coverage with descriptions. The description adds context on default values (days=14, window='1wk'), clamping (days 2-30), and the meaning of window families, enhancing beyond schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and if it's shrinking. This distinguishes it from sibling polymarket_edges which likely gives current state.

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 contrasts fresh edges with older ones, implying when to use this tool for time-series insight. However, it does not explicitly state when not to use or list direct alternatives beyond polymarket_edges.

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 readOnlyHint=true, idempotentHint=true, and no destructive action, which aligns with the description's 'check' nature. The description adds valuable behavioral context: it walks the order-book ladder, returns a verdict (clean|degraded|cannot_fill), and warns about forced directional risk in basket mode. This goes beyond the annotations by detailing operational complexity and edge cases.

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

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

The description is lengthy but well-structured with clear sections for single-market and basket modes, bolded key terms, and a natural flow. Every sentence adds necessary detail given the tool's complexity. Slight verbosity (e.g., the warning sentence about loss mode) could be trimmed, but overall it's efficiently packed with information.

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

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

Despite lacking an output schema, the description thoroughly lists all return values for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill, thin_legs, max_clean_notional_usd, forced_directional_risk for basket. It also covers edge cases like thin legs and partial fills, making it complete for agent decision-making.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds significant value by explaining the nuanced meanings of parameters: size_usd differs for single-market (max spend vs target proceeds) and basket (settlement notional), side defaults and auto-behavior for basket, and the requirement for one of market or event. This enriches the schema's descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and explicitly differentiates from siblings like polymarket_arbitrage and polymarket_edges by prescribing when to use this tool before them. The verb 'check' and resource 'fill risk' are specific and unambiguous.

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

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

The description provides explicit 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 consequences of not using it (partial basket fills causing unhedged directional risk) and specifies required parameters (one of market or event). While helpful, it could more explicitly state when not to use (e.g., for very small trades) and lacks a brief note on 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral details: safety fields, compatibility_warning conditions, temporal alignment, and skipped cross types. 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 and detailed, covering multiple scenarios and safety fields. It is front-loaded with the main purpose, but some details (like the exact list of macro shortcuts) could be condensed. Could be more concise.

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

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

Given the complexity (comparing two venues, compatibility checks, temporal alignment), the description is complete. It describes response fields and safety fields. No output schema but the description compensates well.

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

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

Schema coverage is 100% with each parameter described. The description adds significant context: explains the two modes, how topic/ explicit params interact, and provides examples. This goes 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses specific verbs ('compute', 'compare') and distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on spread analysis with explicit safety checks.

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 two modes (topic shortcuts and explicit tickers) and provides context on when spreads are meaningful (compatibility warning conditions). It lacks explicit contrast with sibling tools like polymarket_arbitrage, but gives clear guidance within its own context.

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, covering safety. Description adds scoping context ('Scoped to your identifier') and pairing hints, but does not detail return format or error behavior. Still adds useful behavioral context beyond annotations.

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

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

Four sentences, each contributing essential information: core action, use case with examples, scoping, and pairing with related tools. No wasted words, front-loaded with 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?

For a tool with one optional parameter and no output schema, the description is remarkably complete. It explains two modes of operation, scoping, examples, and related tools, leaving no ambiguity 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 100%, so baseline is 3. Description reinforces the dual use of the key parameter (omit to list) and provides examples of key content, adding moderate value over 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 verb 'Retrieve' and resource 'value previously saved via remember, or list all saved keys'. Distinguishes from siblings by explicitly mentioning 'remember' and 'forget'.

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

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

Provides explicit when-to-use guidance: 'Use to look up context the agent stored earlier'. Gives concrete examples (ticker, address, research notes) and explains how to list all keys by omitting the key argument. Also suggests pairing with remember/forget.

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

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

The description discloses important behavioral traits beyond the annotations, such as the effect of setting mark_read:true on subsequent calls, and the external consistency with a public URL. It adds significant context about the output fields and filter behavior, fully satisfying the disclosure need.

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 two well-structured sentences. The first covers purpose and output, the second covers filtering and key behavior, and a final sentence adds context about polling and alternative access. Every sentence earns its place 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?

Given the tool's complexity (5 parameters, no output schema), the description is highly complete. It explains the output format, filtering options, mark_read behavior, and external access, providing a thorough mental model for the agent.

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

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

The description adds meaning beyond the input schema by explaining the effect of 'mark_read' and 'since' parameters, and mentions the citation_uri field. With 100% schema coverage, the baseline is 3, but the description enhances understanding of key parameters.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns the most recent alerts with specific fields. It uses a specific verb and resource, but does not explicitly differentiate from sibling tools like 'list_subscriptions' or 'recent_changes', which could be considered 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?

The description provides context for when to use the tool, such as mentioning that polls work fine and the feed is also available via a URL for scripts/dashboards. However, it does not explicitly state when not to use it or suggest alternatives among siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds behavioral details beyond annotations, including the fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, return structure (changes[] grouped by source, total_changes, citation URIs). It does not mention rate limits or performance, but for a read-only tool this is adequate. Scores 4 for significant added 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 paragraph that packs substantial information without wasted sentences. It is front-loaded with example queries. Minor redundancy could be trimmed, but overall efficient and earns its keep.

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

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

Given the tool's complexity (multiple sources, fallback, soft-fail, 3 parameters fully described in schema, no output schema needed), the description covers all critical behavioral aspects, return structure, and provides an alternative tool reference. It is complete for an AI agent to correctly select and invoke the tool.

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

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

Schema coverage is 100%; description adds meaning by explaining the 'since' parameter accepts ISO dates or relative shorthand ('7d', '30d', '3m', '1y') and recommends '30d' or '1m' for monitoring. It also clarifies 'value' can be ticker or CIK, and 'type' only supports 'company'. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool provides a change feed for a company, listing example queries and fanning out to multiple sources. It explicitly distinguishes from the sibling tool 'entity_profile' by noting when to use that instead, thus achieving specific verb+resource and sibling differentiation.

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 examples ('What's new with X', etc.) and states when to use the tool. It also gives an explicit exclusion: 'Use entity_profile instead when you want the static profile', offering clear guidance on alternatives.

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

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

Annotations already indicate idempotent and non-destructive, but the description adds valuable context: key-value scoping by identifier, authentication-based persistence, and session duration. Could have clarified overwrite behavior, but overall good.

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

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

Four sentences, front-loaded with purpose, each sentence adds essential information. No wasted words, clear and efficient.

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

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

For a simple key-value store with good schema and annotations, the description covers purpose, usage, behavioral details, and relationships. No output schema needed; complete and helpful.

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

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

Schema has 100% coverage for two string params with descriptions. The description adds meaning by explaining the key-value pair structure and giving examples, plus the scope by identifier. Slight added value over 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 the specific verb 'Save' and clearly identifies the resource as data for reuse across conversations/sessions. It distinguishes itself from sibling tools 'recall' and 'forget' by explaining the lifecycle.

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 you discover something worth carrying forward') with concrete examples (ticker, address, preference). Also mentions pairing with recall/forget and provides persistence details (24 hours for anonymous).

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

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

Annotations already mark the tool as readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' It also details exact return fields and citation URIs per type, providing transparency beyond the annotations.

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

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

The description is well-organized: opening with illustrative queries, then the core purpose, followed by usage instruction and detailed type support. Every sentence contributes meaningful information without redundancy. It is front-loaded with the most critical information, making it easy to scan.

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

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

Despite lacking an output schema, the description comprehensively explains what the tool returns for each type (ticker, CIK, citation URI for company; RxCUI, ingredient, brand, citation URI for drug). It covers the tool's cascading internal logic and efficiency benefit. No major gaps are apparent 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 description coverage is 100%, so baseline is 3. The description adds value by providing concrete examples for each parameter (e.g., for 'value': 'ticker (AAPL), CIK (0000320193), or name' for company; 'brand or generic name (e.g., "ozempic", "metformin")' for drug). It also explains auto-disambiguation for company lookups. This extra context justifies a score above baseline.

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

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

The description opens with concrete example queries ('What's the ticker for...') and explicitly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It also instructs 'Use FIRST whenever you have a name but need an ID,' making the purpose unmistakably clear. While it does not directly contrast with siblings, the examples and usage instruction sufficiently distinguish it from other tools.

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

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

The description provides strong usage guidance: 'Use FIRST whenever you have a name but need an ID' and 'using resolve_entity replaces 2-3 manual look ups.' It details supported types and what each returns. However, it does not explicitly state when NOT to use the tool or mention alternative tools like entity_profile for deeper information, which would improve this dimension.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds details beyond annotations: it explains that it probes each entity with ai_visibility_check, returns a ranked list with score/confidence/signal density, and requires an _apiKey only for Anthropic model. 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 concise (three sentences) and front-loaded with the main purpose. Every sentence adds value 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 explains return format (ranked list with score, confidence, signal density) and internal behavior (calls ai_visibility_check). All parameters are well-explained, and the tool's context (competitive audits) is clear.

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 meaning: 'First entry treated as subject for narrative', 'context applied to every probe', and clarifies models default. This adds context not present in the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the verb (compare), resource (AI visibility), and distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic compare).

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question. It implies the tool is for comparing multiple entities, distinguishing it from the single-entity ai_visibility_check, but does not explicitly list when not to use it or mention 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?

Adds value beyond annotations by describing the composite nature, potential delay from bundlephobia (5-30s), graceful partial failure with sources_failed list, and return structure. No contradiction with readOnlyHint/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?

Description is dense but every sentence adds value. Could be slightly shorter, but front-loaded with the essential purpose. Still highly effective.

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

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

Given no output schema, description fully explains the return value structure (summary fields, advisory details, links, alternatives) and error behavior (sources_failed). Complete for an agent to understand outcomes.

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

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

Schema coverage is 100% with clear descriptions for both params. Description adds no new param-level info beyond what 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?

Description clearly states it's a composite check for npm packages, combining deps.dev and bundlephobia data. Distinguishes from siblings by noting other ecosystems are handled by deps.dev:version directly.

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 when to use: when an agent asks about npm package safety/popularity/size. Also states limitations: NPM only in v1, other ecosystems go to 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=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the safety profile is clear. The description adds context about searching one state or 'ALL', return fields, and the example, but does not elaborate on pagination, rate limits, or the effect of the _apiKey parameter. This is sufficient but not exceptional given the annotations.

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

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

The description is two sentences plus an example, all front-loaded with the core purpose. Every sentence adds necessary information, and the example clarifies usage. No wasted words.

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

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

Given the tool's complexity (search with 4 parameters, no output schema), the description covers input semantics, example, and sibling linkage. It does not mention pagination or result limits, but these are less critical for a search tool. The annotations provide behavioral safety. Overall, it is nearly complete.

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

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

Schema coverage is 100% with each parameter described. The description adds value by explaining the year code interpretation (1, 2, specific year), the state abbreviation vs 'ALL', and gives an example call. This goes beyond the schema's bare descriptions, earning a 4.

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

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

The description uses a specific verb-resource combination ('full-text search US state and federal legislation') and clearly states the returned fields (number, title, state, last action, bill_id). It distinguishes itself from the sibling tool 'get_bill' by mentioning that you can pass the bill_id to that tool.

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

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

The description explicitly states when to use the tool ('to find out what bills are about a given topic') and provides a concrete example. It does not explicitly mention when not to use it or compare to siblings other than 'get_bill', but the context is clear enough for an agent to decide.

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

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

Beyond annotations (readOnly, idempotent), the description adds embedding model details (BGE-base-en, cosine), windowing strategy (500-char overlapping windows), character cap (200K with truncation flag), and return format (passages with offsets and similarity scores). No contradictions.

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

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

Three well-structured sentences. First sentence states purpose, second gives usage guidance and benefits, third provides technical details. No filler, front-loaded with the key action.

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

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

Despite no output schema, description covers all critical aspects: input constraints, embedding details, return format, truncation behavior, and relationship to sibling. Sufficient for an AI 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% with descriptions. The description adds value by providing examples for 'query' and context for 'text' (e.g., 'SEC 10-K body'). The default for 'limit' is also mentioned. While schema already covers basics, description enriches with usage context.

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 uses a specific verb ('Semantic search INSIDE') and resource ('a fetched record'), clearly distinguishing it from siblings like ask_pipeworx_grounded. It explicitly states the tool's role as a focused search within retrieved data.

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

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

Provides explicit when-to-use ('Use when the record is too big to cram into the prompt'), when-not, and directly names the paired sibling tool 'ask_pipeworx_grounded' for grounding purposes.

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 idempotentHint=true but the description describes creating a new subscription each time, implying non-idempotent behavior. This is a contradiction. The description does add useful behavioral context like OAuth requirement, delivery limits, and webhook secret one-time return, but the contradiction reduces clarity.

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

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

The description is well-structured with clear sections for supported types and delivery channels. It is lengthy but each sentence adds value; no wasted words.

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

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

Given the tool's complexity (multiple subscription types, multiple delivery channels), the description covers prerequisites, type-specific params, and delivery behavior. It explains the return value (subscription id) despite no output schema. Minor gaps like idempotence handling are not addressed.

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 enriches parameters with detailed examples and clarifications (e.g., sec_8k items meaning, delivery channel behavior), adding value beyond the schema.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' and specifies it returns the new subscription id. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description gives clear context on when to use (to create a subscription) and prerequisites (requires Pipeworx OAuth account, no anonymous/BYO). However, it does not explicitly state when not to use or alternatives, though siblings imply different purposes.

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. The description adds that the tool returns example questions with exact tool+argument shapes, drawn from the live catalog. No contradictions and useful behavioral detail.

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

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

The description is relatively long but well-structured, front-loading key phrases and then providing details. Every sentence adds value; it could be slightly trimmed but remains 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?

Given the tool's role as an onboarding entry point with no output schema, the description covers the return shape (category-bucketed examples with tool calls), usage patterns, and purpose. It is complete and informative.

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

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

Schema coverage is 100% with one parameter (topic). The description adds concrete examples ('finance', 'pharma', 'betting') and explains the effect of omitting vs. using the topic, providing meaning beyond the schema 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 purpose: it's the onboarding entry point for an agent, returning category-bucketed example questions. It uses specific verbs and resources, distinguishes from siblings like ask_pipeworx and discover_tools by emphasizing 'use this FIRST'.

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 when to use ('when you do not yet know what Pipeworx can do') and how (no arguments for full spread, or pass topic). It implies it's the first tool to call. It doesn't explicitly list when not to use, 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 indicate destructiveHint=false, and the description adds that the row is deactivated not deleted, with historical events available via recent_alerts. This goes beyond annotations, providing critical behavioral context.

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

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

Two sentences, each carrying essential information: action, ownership, and behavioral detail. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, constraints, and effect comprehensively. It also mentions a related tool (recent_alerts) for follow-up.

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

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

Schema coverage is 100% for the single parameter 'id'. The description reinforces that the id comes from 'subscribe', adding value beyond the schema 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 verb and resource: 'Cancel a subscription by id.' It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying the action and scope.

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

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

It explicitly says 'Ownership is enforced — you can only cancel your own subscriptions,' providing a clear when-to-use condition. It does not mention alternatives, but the ownership constraint is a strong guideline.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the return fields (verdict, structured form, actual value with citation, percent delta) and the data source (SEC EDGAR + XBRL). 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 lengthy but avoids fluff. Each sentence adds value, including usage examples, domain scope, and output details. Could be slightly more structured, 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?

For a single-parameter tool with no output schema, the description is thorough: it explains the domain, supported claims, data sources, output structure, and replaces multiple calls. No missing information given the tool's simplicity and annotation coverage.

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

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

The only parameter 'claim' has a schema description with examples. The tool description adds further context on claim format and supported types (e.g., revenue, net income), providing meaning beyond the schema. Given 100% schema coverage, this is solid.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, with explicit examples of triggers and the specific domain (company-financial claims). It distinguishes itself from siblings by noting it replaces multiple sequential calls.

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' and clarifies the supported domain. It does not provide explicit when-not-to-use or alternative tools, but the context is clear enough.

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