Abgeordnetenwatch

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: default model is free, API key is passed through to Anthropic, and the return format includes per-model fields. 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 two sentences plus a use-case sentence, front-loaded with the primary action, and contains no unnecessary words. 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?

Despite no output schema, the description specifies the return fields (score, confidence, signals, raw_response) and a combined view. The tool has 4 params all covered in schema, and the description covers usage, behavior, and output adequately.

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 all parameters. The description adds minimal parameter-level detail beyond noting that `_apiKey` is needed for Anthropic, which is acceptable given baseline 3.

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

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

The description uses specific verbs ('probe', 'score') and clearly identifies the resource ('LLMs for visibility'). It distinguishes itself from sibling tools by focusing on AI visibility scoring, which no other sibling tool does.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional `_apiKey` parameter. It does not explicitly state when not to use the tool or compare directly with siblings, but the context is clear.

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

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

Annotations already declare the tool read-only, open-world, and idempotent. The description adds valuable context: it routes to thousands of tools, returns structured answers with citation URIs, and is fast. 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 directive 'PREFER OVER WEB SEARCH', uses bold for emphasis, and organizes examples and sibling tool guidance well. However, it is somewhat lengthy and could be tightened.

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,245 tools, no output schema), the description covers what the tool does, when to use it, and gives examples. It mentions structured answers with citations, which provides some output context, but could elaborate on the answer format.

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

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

The input schema has 6 parameters all aliases for the question, with 100% schema coverage. The description mainly restates that the tool accepts natural language questions but does not add new semantic detail beyond the schema and examples.

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

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

The description clearly identifies the tool as a query engine for structured data from many sources, with a specific verb 'ask' and resource 'Pipeworx'. It distinguishes from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point.

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

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

The description explicitly states when to use this tool over web search, provides examples of query types, and gives clear guidance on when to step up to grounded or deep research alternatives. It also notes the tool works on every tier.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context: no candidate currently active, so behavior matches ask_pipeworx exactly. It also states it is a full working router, not a fallback, which goes beyond annotations.

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

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

The description is 5 sentences, providing necessary context without excessive verbiage. It is front-loaded with purpose. Slightly long 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?

Given the tool's complexity (beta, identical to stable, experimental routing), the description is thorough: explains purpose, current state, usage instructions, and relation to sibling. No output schema needed as shape matches ask_pipeworx.

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 aliases fully documented. The description does not add extra meaning for parameters, but baseline for high coverage is 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 this is a beta version of ask_pipeworx, identical in tools and arguments, used for testing routing improvements. It explicitly distinguishes itself from the stable ask_pipeworx by labeling it as the experimental edge.

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: 'when you want the newest routing' and implies the alternative (use stable ask_pipeworx otherwise). It also explains the fallback behavior and that results are compared against the stable router.

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

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

Annotations already provide readOnlyHint and idempotentHint, indicating safe read operations. The description adds valuable context about the refusal mechanism, return structure (answer, evidence, confidence, etc.), and the cost of an extra LLM call. 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 every sentence adds value: it states purpose, mechanism, use cases, return format, and cost. It is front-loaded with the core purpose. Slightly verbose but efficient overall.

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 is provided, so the description compensates by explaining the return structure and refusal reasons in detail. For a tool with 6 parameters (all aliases) and complex behavior, it covers essential aspects like when refusals occur and evidence extraction.

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

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

Schema coverage is 100% with all parameters being aliases for 'question'. The description mentions these aliases, which matches the schema but adds little additional meaning beyond listing examples. Baseline 3 is appropriate as the schema already documents the parameters thoroughly.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains its mechanism: it extracts answers only from tool results and provides explicit refusals. It distinguishes itself from the sibling tool 'ask_pipeworx' by noting the extra LLM call and use case.

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: 'for high-stakes reads' when the answer will be quoted, cited, or acted on, and the agent must not invent facts. It also advises to prefer 'ask_pipeworx' for casual lookups, providing clear alternatives.

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

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

The description extensively discloses behavioral traits beyond annotations: resolver contract, fan-out logic, response shapes, safety mechanisms, handling of closed markets, wide spreads, and resolution-rule risk. All annotations (readOnly, idempotent, openWorld, non-destructive) are consistent and supplemented with actionable details.

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 and front-loaded with essential information. Every sentence adds value given the tool's complexity. Slight reduction could improve conciseness, but the detail is justified for agent comprehension.

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?

Without an output schema, the description comprehensively explains return values: response shapes, resolver contract, parent event extractor, news fields, and safety checks. It covers all necessary aspects for an agent to correctly invoke and interpret 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 detailed parameter descriptions. The tool description adds some context for 'market' (input forms) but mirrors schema for 'depth' and 'include_raw'. Baseline 3 is appropriate as description adds little value beyond schema.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It identifies the specific resource (Polymarket bet) and action (research via Pipeworx data), and provides use cases. While it doesn't explicitly differentiate from siblings, the detailed scope implies distinction.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It offers clear context but does not directly compare to alternatives or specify when not to use, leaving some ambiguity among sibling tools.

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

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

Annotations already mark as read-only, open-world, idempotent, non-destructive. The description adds rich behavioral context: for companies it pulls specific financial data (revenue, net income, cash, debt from SEC XBRL), handles fiscal years, sorts by primary metric; for drugs it pulls FAERS counts, FDA approvals, trials. 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 longer but each sentence adds value: trigger phrases, action, data sources, sorting behavior, efficiency note. Could be slightly trimmed, but no filler. Front-loaded with user intent examples.

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 notes return format: paired data with citation URIs. It covers entity types, data sources, sorting, and efficiency. The 2-parameter tool with 100% schema coverage is well-documented overall.

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

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

Schema coverage is 100%, so baseline is 3. However, description adds meaning by explaining how each parameter is used (e.g., type='company' pulls financial data from EDGAR, type='drug' pulls adverse event counts; values expects tickers/CIKs for companies, names for drugs). This extra context warrants 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 that the tool performs side-by-side comparison of 2-5 companies or drugs, with example phrases. It explicitly distinguishes from sequential single-entity lookups, making the purpose and unique value very clear.

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

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

The description provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It lists trigger phrases and covers when to use, though it doesn't explicitly state when not to use (e.g., for single entity data).

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are present. Description adds extensive details: account requirement, parallel execution, depth-specific behaviors (gap recovery, contradictions, hop field), findings packet structure (verbatim evidence, confidence, source, citation, gaps, contradictions), semantic excerpting, expected response times, and handling of topics not in catalog.

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 front-loaded with critical prerequisites (account requirement, alternative). It is thorough but slightly verbose; however, every sentence provides unique value given 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?

Despite no output schema, the description thoroughly explains the return structure (findings packet with evidence, confidence, source, citation, gaps, contradictions). Covers prerequisites, timing, iteration behavior, and edge cases (empty gaps for uncataloged topics). Complete for an agent to use correctly.

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

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

Schema covers both parameters (question, depth) with 100% coverage. Description adds significant context: explains depth values (quick=3 facets, standard=5+gap recovery+contradictions, thorough=8+iterative+contradictions) and clarifies that broad questions are intended.

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 across 1369 structured data sources, decomposes questions into facets, and returns a findings packet. It distinguishes itself from ask_pipeworx (single lookup) and specifies it is not open-web search.

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

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

Explicitly tells when to use (broad/multi-part questions over structured data) and when not (breaking news, single lookup, if not signed in). Provides alternative ask_pipeworx for other cases.

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

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

Annotations already declare readOnlyHit=true and idempotentHint=true. The description adds that it returns top-N tools with full schemas ready to call directly, explaining what the agent can expect. No contradictions.

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

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

The description is somewhat lengthy but front-loads the core purpose and usage. Every sentence adds value, though some redundancy could be trimmed.

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

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

Given the complexity of a discovery tool among many specific siblings, the description covers purpose, usage, and return format. No output schema exists, but description explains what is returned, which is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant new meaning beyond the schema's parameter descriptions. It lists aliases but those are already in the schema.

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

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

The description clearly states it finds tools by describing data/task. It lists many example domains and distinguishes itself from sibling tools as the discovery tool, not a specific function. The verb 'find' and resource 'tools' are specific.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set'. This provides clear context and contrasts with specific sibling tools.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds substantial behavioral context: it fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), lists exactly what is returned (cik, recent_filings with URI, fundamentals, patents, news, LEI), and notes the USPTO API sunset. 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 detailed but well-structured, starting with user-facing examples then explaining capabilities and return fields. Every sentence adds value. It could be slightly more concise, but the level of detail is warranted for a complex profile tool.

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

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

Given the tool's complexity (multi-source profile), 2 params with full schema descriptions, and no output schema, the description is comprehensive: it enumerates all return fields, explains behavior for each source, mentions limitations, and references a sibling tool. No gaps are apparent.

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 already covers both parameters with descriptions (100% coverage). The description adds value by clarifying that 'value' can be a ticker or zero-padded CIK, explicitly says names are not supported, and provides example inputs ('AAPL', '0000320193'). This goes beyond the schema's 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 opens with common user queries like 'Tell me about X' and 'company profile for Microsoft', then precisely states it provides a 'full cross-source profile of a US public company in ONE parallel call.' This clearly defines the verb+resource and distinguishes it from sibling tools such as resolve_entity.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and 'Names not supported — use resolve_entity first if you only have a name.' This provides clear when-to-use and when-not-to-use guidance, including an alternative tool.

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

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

Annotations already include destructiveHint: true, so the destructive nature is expected. Description adds context about clearing stale or sensitive data, which is helpful but not extensive. 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?

Two sentences: first states purpose, second provides usage guidelines. No unnecessary words, front-loaded, efficient.

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

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

For a simple tool with one required parameter and no output schema, the description is complete. It covers purpose, usage context, and pairs with related tools. Annotations provide the destructive warning.

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

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

Schema coverage is 100%, so the description adds no new parameter details beyond 'Memory key to delete'. 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?

Clearly states it deletes a memory by key, with a specific verb (Delete) and resource (memory by key). References sibling tools (remember, recall) to differentiate.

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

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

Explicitly states when to use (stale context, task done, clear sensitive data) and pairs with other tools (remember, recall), providing clear guidance on when to invoke this tool vs alternatives.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds process details (fetches page, extracts title/description/links, emits standard markdown) and output format, providing 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?

Two concise sentences plus a bullet list of use cases. Front-loads the main action. Every sentence adds value with no redundancy.

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

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

Covers purpose, behavior, output format, and use cases. No output schema exists, but description explains output as 'a single text blob ready to drop at site-root/llms.txt', which is sufficient for such a simple tool.

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

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

Schema coverage is 100% with adequate descriptions for both parameters. The description doesn't add significant new parameter-level meaning, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('Generate') and resource ('llms.txt file for any URL'), and clearly distinguishes from sibling tools which are mostly about politicians, polls, and betting.

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

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

Lists explicit use cases (getting a client's site indexed, drafting for own project, auditing competitors) but does not mention when not to use or compare to alternative tools, which are not needed given sibling dissimilarity.

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 readOnly, idempotent, openWorld, and non-destructive. Description adds specific output fields (name, party, year of birth, sex, education, residence) beyond annotations, giving full behavioral context. No contradiction.

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

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

Two sentences, front-loaded with verb and resource, no filler. 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?

Simple tool: single required param, no output schema needed. Description covers purpose, input source, and returned fields. Fully informs agent 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 covers 100% of parameters with description for 'id'. Description reiterates the parameter and adds context on where to obtain the id (search_politicians), providing extra guidance beyond schema.

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

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

Clearly states verb 'Get', resource 'full profile of a single German politician', and specifies the input (Abgeordnetenwatch id) and output fields (name, party, year of birth, sex, education and residence). Distinguishes from sibling tool search_politicians.

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

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

Explicitly says 'Get the id from search_politicians', guiding the agent to first use that tool. While it lacks a when-not-to-use, this guidance is clear for a straightforward lookup.

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. Description adds value by specifying the exact entities (Bundestag, Landtage, EU parliament) and return fields (id, short name, full official name). No contradictions.

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

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

Three sentences, no filler, front-loaded with main purpose, then details and usage advice. Every sentence adds value.

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

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

With no params, complete annotations, and simple output (ids, names), the description fully covers what the tool does, returns, and why to use it. No output schema needed.

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?

No parameters exist, so schema coverage is 100%. Baseline 4 applies; description adds no parameter info as none are needed.

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 explicitly states the tool lists German parliaments (Bundestag, Landtage, EU parliament) and returns id, short name, full official name. Clearly distinguishes from sibling tools like list_polls or entity_profile.

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

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

Explicitly states to use the tool to get parliament ids for scoping politician or poll queries. Provides clear context, though no exclusions or alternative tools are mentioned.

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

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

Annotations already provide readOnlyHint, idempotentHint, constructiveHint. Description adds ordering ('most recent first'), which is valuable beyond annotations. 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?

Two sentences, front-loaded with purpose, then optional parameter, then ordering. 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?

Description mentions return fields (title, date) but no output schema exists. For a simple list tool with annotations, this is complete enough. Could mention pagination behavior but not critical.

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 both parameters (limit, period_id) are already described in schema. Description repeats period_id but adds no new semantics beyond what schema provides. Baseline 3.

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

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

Clearly states verb (List) and resource (parliamentary votes/polls) with specific attributes (title, date). No sibling tool duplicates this function, so it's distinct.

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

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

Explicitly mentions optional filtering by period_id, giving clear context for use. However, it does not specify when to use this tool vs. alternatives, though none exist 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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns specific fields and mentions the include_inactive parameter. No contradiction; adds moderate 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?

Two sentences with no filler. First sentence states purpose and return fields; second sentence gives usage guidance. Front-loaded 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 list tool with one optional parameter and no output schema, the description is fully adequate. It covers purpose, return fields, and usage context. No gaps identified.

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 input schema already describes the only parameter (include_inactive) with a clear description. The tool description does not add new meaning to the parameter beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions' with specific verb and resource, and lists return fields including id, type, params, timestamps, and fire_count. This distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear context on when to use the tool. Does not explicitly mention alternatives but context is sufficient.

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

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

Discloses rate limiting (5 per identifier per day), free usage, and that it doesn't count against tool-call quota—details beyond annotations. No contradictions; annotations are neutral and consistent.

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 single paragraph with no wasted words. Key information (purpose, use cases, restrictions) is front-loaded and well-organized.

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

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

Fully addresses the tool's purpose, parameters, and behavioral nuances. No output schema needed; tool is simple and description covers all necessary context for correct 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 description coverage is 100%, so the schema already explains parameters. The description adds context on how to use the 'type' and 'context' fields (e.g., specifying pack/tool/vertical) and message length limits, but this adds only modest value beyond schema.

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

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

Clearly identifies the tool's purpose: sending feedback (bug, feature, data_gap, praise) to the Pipeworx team. Distinct from all sibling tools which perform queries or actions unrelated to 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 states when to use each feedback type (bug, feature, data_gap, praise) and provides negative guidance (don't paste end-user prompt). Also covers rate limits and usage constraints (5/day, free, no quota).

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, destructiveHint. The description adds valuable behavioral context: self-aggregating, no PII, caching behavior (5min-1h), and derivation from CF analytics-engine. 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 a clear first sentence stating purpose, followed by bulleted use cases and metadata. Slightly verbose (e.g., 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)') but front-loaded and no wasted sentences.

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

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

Given no output schema, the description specifies return types ('top tools, top packs, total call volume') but not the exact structure (e.g., list format, counts). However, with only one parameter and clear purpose, it's sufficient for agent selection.

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

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

Schema has 100% coverage with enum descriptions. The description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds meaning beyond the schema's enum 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 returns 'top tools, top packs, and total call volume over a recent window,' with specific verbs and resources. It distinguishes itself from siblings by being specific to Pipeworx trending data, notably different from 'discover_tools' or others.

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

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

The description lists three concrete use cases (discovering hot data sources, confirming canonical choice, aligning use case) and explains how different windows serve different purposes. It lacks explicit alternatives or when-not-to-use guidance, 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 already indicate read-only, idempotent, non-destructive behavior. The description adds critical behavioral details: realizable vs theoretical edge, when not to trade, partition filter logic, and similarity threshold. 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 detailed but well-structured, front-loading core purpose and mode differentiation. Some redundancy could be trimmed, but every sentence adds value for a complex tool.

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

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

Despite no output schema, the description fully specifies the response structure (opportunities array, partition_check fields, fill check details) and references complementary tools. 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%, and the description enriches both parameters with usage examples ('fed-decision-may-2026'), accepted formats (URLs), and behavioral consequences of each parameter value.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific use cases, making the tool's purpose unambiguous.

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

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

Explicitly tells when to use each mode (trending scan, per-event, cross-event) and recommends event for specific markets. Also cross-references sibling tool polymarket_fill_risk for custom sizing, providing clear alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context: caching (1h KV level keyed on knobs), output structure (by_segment, fed_candidates, diagnostics), and detailed model families. 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 verbose (over 300 words) and dense with technical detail. While valuable, it could be restructured with bullet points or clearer sections. The front-loading of purpose is good, but the depth may overwhelm agents.

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

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

Given the tool's complexity (9 parameters, multiple segments, diagnostics, no output schema), the description is very complete. It explains tradeable-edge knobs, diagnostics, caching, and Fed bets. Without an output schema, it describes the response structure thoroughly.

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

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

Schema coverage is 100% with descriptions for all 9 parameters. The description adds value by explaining high-level behavior of tradeable-edge knobs and providing deeper context for min_partition_leg_kelly beyond the schema. This justifies a slight increase beyond baseline 3.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It is action-oriented and distinguishes from sibling tools by focusing on discrepancy detection for betting.

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 'Built for "what should I bet on today"' and provides context about Fed bets and caching. However, it does not explicitly contrast with siblings like polymarket_arbitrage or polymarket_edge_tracker, which would help agents choose.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds detailed behavioral traits: computed trend/decay fields, expired opportunities with lifespan, snapshot gaps due to cache misses, and limitations (60-day TTL, daily closes not intraday). These go well beyond annotations.

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

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

Description is somewhat long but well-structured: purpose in first sentence, then example question, then args, then detailed response fields. Each sentence adds value, but could be slightly more terse. Front-loads the core question.

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 fully explains the response structure (tracked[], expired[], snapshot_dates[]) and covers edge cases (gaps, TTL bounds). All necessary behavioral and output details are provided.

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

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

Schema coverage is 100% with descriptions for both parameters. Description reinforces defaults (14 days, '1wk') and max days (30), adding modest value beyond schema. No enums.

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 states specific verb+resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly distinguishes from siblings by focusing on historical tracking of edge existence and decay, unlike `polymarket_edges` which likely provides current edge 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?

Explicitly answers the question 'how long has this edge existed and is it shrinking?' and contrasts fresh vs. old wide edges, providing clear context for when to use this tool. Does not list alternatives or when-not-to-use, but the context is sufficient.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, indicating safe read operations. The description adds behavioral context beyond annotations, such as the tool's return values (verdict, slippage, fill details) and the risk of partial fills. 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 well-structured with clear sections (SINGLE-MARKET, BASKET) and front-loaded purpose. It uses all-caps for important warnings. While it is somewhat verbose, every sentence adds value, and the structure makes it easy to parse.

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

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

Given the tool's complexity (two modes, multiple return fields) and the absence of an output schema, the description comprehensively covers both input usage and expected outputs (e.g., lists return fields for each mode). It also explains edge cases like thin books and forced directional risk, ensuring no gaps for the agent.

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

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

Schema coverage is 100% with non-empty descriptions. The description adds significant meaning by explaining how parameters behave in each mode (e.g., size_usd interpretation differs for single vs basket, side defaults), and clarifies the relationship between parameters (e.g., market vs event mutually exclusive). This goes well beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and specifies the return verdicts (clean, degraded, cannot_fill), leaving no ambiguity about what the tool does.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the risk of not using the tool (partial basket fills convert arb to unhedged position) and differentiates it from sibling tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds rich behavioral context: how the two modes work, response structure (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment), and counters for skipped comparisons. No contradiction.

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

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

The description is fairly long but well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the primary purpose and every sentence adds necessary detail. Could be slightly more concise but not excessive.

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

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

Given the tool's complexity, the description covers all necessary aspects: modes of operation, response format, safety warnings, temporal alignment, and edge cases. No output schema, but the description describes the response adequately.

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

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

Schema description coverage is 100%. The description adds value by explaining the override behavior of explicit tickers over topic, and listing the 10 pre-mapped topics with their meaning.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage (intra-venue) and research 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 explains two modes (topic shortcuts and explicit tickers), warns about compatibility warnings and temporal alignment, and implies not to use when a compatibility warning is issued. However, it does not explicitly compare to alternatives among the 30+ sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: that listing all keys is done by omitting the key argument, and that the tool is scoped to an identifier. This adds beyond annotations without contradiction.

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

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

The description is three well-structured sentences, front-loaded with the main action. Every sentence serves a purpose: stating the action, explaining usage context, and noting scoping and related tools. 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 low complexity (one optional parameter, no output schema, rich annotations), the description is complete. It explains behavior, usage context, scoping, and pairing with related tools. No output schema is needed for a read operation returning a simple value.

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

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

Schema coverage is 100% with a clear description of the 'key' parameter. The description repeats the schema's note about omitting to list all keys but adds examples of key types (ticker, address, notes). Since schema already does heavy lifting, this adds marginal value, earning a baseline 3.

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

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

The description clearly states the tool retrieves saved values or lists all keys, with specific verb 'Retrieve' and resource 'value previously saved via remember'. It distinguishes itself from sibling tools 'remember' and 'forget' by explicitly mentioning them and contrasting their functions.

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: to look up previously stored context without re-deriving. It implies when not to use (use remember to save, forget to delete). It also mentions scoping by identifier, providing clear context for usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety profile is known. The description adds behavioral context beyond annotations: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This explains a side effect that is not obvious from annotations. It also clarifies that the feed is persisted and returned events are recent. 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 a single paragraph of about 5 sentences with clear front-loading: the first sentence states the core purpose. Each subsequent sentence adds specific details (return fields, filtering, mark_read, alternative access). There is no repetition or fluff. The length is appropriate for the complexity of the tool.

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

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

The description explains what the tool returns (source, citation_uri, raw payload) even though there is no output schema. It covers filtering, side effect of mark_read, and comparison to an HTTP endpoint. For a read-only polling tool with 5 optional parameters, this provides sufficient context for an agent to use it correctly. The absence of output schema is compensated by description of return fields.

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

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

The input schema covers all 5 parameters with descriptions (100% coverage). The description adds value by providing usage context: 'Filter by type (e.g. 'sec_8k') and/or since (ISO timestamp).' It also explains the mark_read parameter's side effect. However, it does not elaborate on limit or unread_only beyond what schema provides, but the schema descriptions are sufficient. The description helps an agent understand how to combine parameters 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 'Pull fired events from your subscription feed' with specific verb 'Pull' and resource 'fired events from subscription feed'. It tells what kind of data is returned (source, citation_uri, raw payload) and how to filter/side-effect. It distinguishes this tool from other alert-related tools like list_subscriptions by focusing on the feed of fired events.

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

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

The description provides explicit guidance: 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' This indicates when to use the tool (polls) versus an alternative (HTTP endpoint). It also gives filtering examples (type='sec_8k', ISO timestamp for since) and explains mark_read behavior. However, it does not explicitly list siblings or state when not to use this tool.

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

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

The description discloses multi-source fan-out (SEC, GDELT/GNews, USPTO), fallback behavior, soft-fail for patents, and input format details. Annotations already declare readOnlyHint, idempotentHint, etc., but the description adds substantial behavioral context beyond that.

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 front-loaded with query examples. Every sentence contributes useful information. Could be slightly more concise, but still effective.

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

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

Given the tool's complexity (multiple sources, fallback, soft-fail, output format), the description covers all relevant aspects. It describes the output structure (changes[], count, URIs) despite no output schema, and handles the variations 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%, but the description adds value by explaining the 'since' parameter accepts ISO or relative shorthand with examples, and clarifies 'value' can be ticker or CIK. It also notes 'type' is limited to company.

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

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

The description clearly states it provides a change feed for a company in a time window, using verbs like 'latest' and 'updates'. It distinguishes from sibling tool entity_profile by explicitly saying when to use that instead.

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 includes explicit guidance on when to use entity_profile instead, and provides example queries that map to this tool. It does not explicitly state exclusions, but the differentiation 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 non-read-only, idempotent, non-destructive. Description adds that data is scoped by identifier and memory duration (24h for anonymous, persistent for authenticated). No contradictions, but could mention limits like key/value length if any.

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

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

Four sentences, front-loaded with purpose, no wasted words. Each sentence adds value: purpose, when to use, storage behavior, pairing with other tools.

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 2 params, no output schema, and annotations present, the description covers usage, persistence, and pairing. Sufficient for an agent to use correctly.

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

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

Schema covers both parameters with descriptions (100% coverage). Description does not add new semantics beyond examples, but it's consistent. Baseline score of 3 is appropriate as schema already does the heavy lifting.

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

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

Clearly states the tool's purpose as saving data for later reuse across conversations or sessions. Provides examples of what to store (resolved ticker, target address) and distinguishes from sibling tools like recall and forget.

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

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

Explicitly specifies when to use: 'when you discover something worth carrying forward'. Pairs with recall and forget, and explains scoping and persistence differences between authenticated and anonymous sessions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds that the tool cascades through several lookup endpoints internally and provides details on the return types for each entity type (e.g., ticker + CIK for company), which enhances transparency beyond annotations.

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

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

The description is well-structured with a clear lead sentence listing query examples, bolded entity types, and a concise note about internal cascading. Every sentence adds value; no redundancy or fluff.

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

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

Given the two required parameters and no output schema, the description adequately covers input semantics and output expectations per entity type. It mentions that the tool replaces multiple lookups, giving context on efficiency. Minor omission: no mention of potential errors or rate limits, but annotations cover safety.

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

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

Schema coverage is 100%, but the description adds meaningful context: for the 'type' enum, it specifies what each returns; for 'value', it gives examples of accepted inputs (ticker, CIK, names) and clarifies auto-disambiguation. This goes beyond the schema's basic 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 resolves names to official identifiers with specific examples like 'What's the ticker for…' and lists supported entity types (company, drug). It distinguishes itself by emphasizing this is the first tool to use when you have a name but need an ID, differentiating it from sibling tools that may already use IDs.

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 FIRST whenever you have a name but need an ID,' giving clear when-to-use guidance. It also notes that each call replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly state when not to use it or list alternatives, though the context implies avoiding it when an ID is already available.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so baseline safety is clear. The description adds value by explaining internal mechanism (probes each entity with ai_visibility_check, ranks by score) and output format (ranked list with score, confidence, signal density). No contradictions.

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

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

Three sentences with clear front-loading: first sentence states core purpose, second explains mechanism, third provides usage example. No unnecessary words.

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

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

Given 4 parameters (1 required), no output schema, the description covers purpose, mechanism, output format, and usage scenario. Missing details like error handling or limits, but for a read-only tool with strong annotations it's sufficiently complete.

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

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

Schema description coverage is 100%, so baseline is moderate. The description adds extra context beyond schema: the first entity is treated as 'subject' for narrative, and context is shared across probes. This adds meaningful guidance for agents.

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 uses a specific verb (compare) and resource (AI visibility across entities), and distinguishes itself from siblings like ai_visibility_check (single entity check) and compare_entities (likely broader comparison).

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 case: competitive AI-marketing audits, with an example ("does Claude know about us as well as our competitors?"). It gives context (first entity as subject, rest as competitors), but does not explicitly state when NOT to use or name alternatives, though it's clear enough from 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 readOnly, idempotent, not destructive. The description adds specific behavioral details: fans out to two external services, bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully with sources_failed list.

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

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

The description is moderately long but well-structured and front-loaded with the core purpose. Every sentence adds value, though it could be slightly tighter without losing 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?

Even without an output schema, the description comprehensively lists return fields (summary block with ~8 attributes, per-advisory detail, links, alternative versions). Also covers edge cases (scoped packages, version default, timeout behavior, partial failures).

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 adds value by explicitly mentioning that scoped packages like '@types/node' are accepted, which is not fully implied by the schema's description.

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

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

The description clearly states the tool's purpose: a composite check for adding npm packages, covering license, advisories, version history, and bundle size. It distinguishes itself from siblings by noting it is NPM-only in v1 and that other ecosystems use a different 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?

Explicitly says when to use: when an agent asks about safety, popularity, size, or cost of adding a package. Also gives alternatives for non-NPM ecosystems (deps.dev:version directly) and warns about potential timeout on first bundlephobia measurement.

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, and idempotentHint=true. The description adds valuable behavioral context: it specifies the search is a contains-match, returns party, year of birth, and sex, and provides example queries. 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 two clear sentences plus an example, with no wasted words. It front-loads key information.

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

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

For a simple search tool, the description covers the core purpose, search behavior, returned fields, and links to the sibling tool for full profiles. It is complete given the lack of an output schema.

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

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

Schema coverage is 100%, so the description does not need to add much. It reinforces the contains-match behavior and provides examples, but the schema already explains both parameters adequately.

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

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

The description clearly states the verb 'Search', the resource 'German federal and state politicians', and the search method (contains-match by surname). It also distinguishes from the sibling 'get_politician' by recommending it for full profiles.

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

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

The description explicitly states when to use this tool (search by name with contains-match) and when to use the alternative 'get_politician'. It provides clear context for usage, though no explicit exclusion scenarios are mentioned beyond the alternative.

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

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

Annotations provide readOnlyHint, etc. Description adds technical details: embedding model (BGE-base-en), window size (500-char), char cap (200K with truncation flag), and return of offsets. This adds value beyond annotations.

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

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

Four sentences, no wasted words. Key info (purpose, usage, limitations) front-loaded. Highly efficient.

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

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

No output schema, but description explains return values (passages with offsets and scores). Covers input constraints, behavior, and pairing. Still could mention expected output format more explicitly.

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: examples for query parameter, truncation info for text, and context for limit. This complements the schema well.

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

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

The description clearly states it performs semantic search inside a fetched record, with specific verb+resource. It distinguishes itself from sibling tools like ask_pipeworx_grounded by focusing on passage retrieval with offsets and character limits.

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 states when to use (record too large for prompt, save context) and pairs with ask_pipeworx_grounded. It does not explicitly state when not to use, but context is clear enough for an agent.

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

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

Annotations only indicate non-read-only, non-destructive, idempotent, open-world. The description adds significant behavioral context: subscription persistence requires OAuth, delivery channel behaviors (sms cap, webhook auto-disable after 10 failures, HMAC signing, secret returned once), and type-specific parameter details. No contradiction with annotations.

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

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

Description is dense but well-structured: purpose and return value first, then requirements, supported types with examples, then delivery channels. At ~150 words, it efficiently packs information without fluff, though could be slightly more concise.

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

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

Given the tool's complexity (3 params, nested objects, 5 types, multiple delivery channels, no output schema), the description covers creation semantics, auth constraints, all type examples, delivery behaviors, and constraints. Missing: confirmation of idempotency behavior (but annotation covers it) and explicit return value format (but 'new subscription id' is stated).

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

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

Schema coverage is 100%, baseline 3. Description adds value beyond schema by providing examples for each type (e.g., sec_8k items codes, polymarket_edge topic, fred_series series_id) and clarifying delivery constraints (e.g., sms verification requirement, webhook auto-disable logic, signing secret).

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. Returns the new subscription id.' The verb 'Create' and resource 'subscription' are specific, and 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 provides explicit context: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It also details channel constraints (sms verification, cap, webhook auto-disable). However, it does not explicitly state when to avoid this tool or directly compare to 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, openWorldHint, idempotentHint, and destructiveHint. The description adds context about the output structure (category-bucketed example questions with exact tool+argument shapes) and that it draws from a live catalog. It does not contradict annotations and provides additional useful behavioral context beyond what annotations convey.

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 that is front-loaded with common queries and then explains the output and usage. It is informative without being verbose, though it could be slightly more structured with bullets. Still, it is well-organized and every sentence adds value.

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

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

Given the tool's purpose as an onboarding entry point and the absence of an output schema, the description adequately explains the output format (category-bucketed with tool+argument shapes) and usage. It covers the primary use case and provides enough context for an agent to understand the tool's purpose and behavior.

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

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

The schema has 100% coverage with a single parameter 'topic' described. The description enhances this by listing the specific focus areas ('finance, pharma, economics, ...') and clarifying that omitting it returns a cross-category spread. This adds meaning beyond the schema's generic 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 that the tool returns category-bucketed example questions to help users understand what Pipeworx can do. It uses specific verbs ('returns') and specifies the resource ('category-bucketed example questions'). It also distinguishes itself as the onboarding entry point, contrasting with other tools indirectly by stating '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 tells when to use this tool ('Use this FIRST when you do not yet know what Pipeworx can do for you') and how to use it ('Call with no arguments for the full spread, or pass `topic` to focus'). It also provides guidance on learning meta-tools. This is comprehensive and 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 provide idempotentHint=true and destructiveHint=false, but the description adds critical context: the row is deactivated, not deleted, and historical events remain available via recent_alerts. This explains the non-destructive nature beyond mere hints.

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

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

Two sentences, front-loaded with action ('Cancel a subscription by id'), and second sentence adds essential nuance. No redundant 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, behavioral side effects, and data retention. The agent has enough information to use the tool correctly.

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

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

Schema has 100% coverage with one parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

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

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

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

The description mentions ownership enforcement ('you can only cancel your own subscriptions'), implying self-cancellation, but does not explicitly state when to use this tool vs alternatives or provide exclusion criteria.

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 thoroughly details behavioral traits: it explains the two sub-paths (SEC EDGAR+XBRL for financial claims, grounded pipeline for others), the return format (verdict, actual value with citation, reasoning), and that it replaces multiple sequential calls. This adds significant context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). 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 long but well-structured: it opens with the core purpose and query examples, then explains the two processing paths and return value. Every sentence adds value, though minor trimming could improve conciseness without losing 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 complexity and the presence of annotations and full schema coverage, the description is complete. It explains what the tool does, how it processes different claim types, and what it returns. No output schema is needed as the return format is fully 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%, but the description adds substantial meaning: it explains the 'claim' parameter with examples and clarifies 'tolerance_pct' with its purpose, default behavior, and interaction with claim wording. This goes well beyond the schema definitions.

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: natural-language claim verification against authoritative sources. It lists typical query phrasings and distinguishes two processing paths (financial vs. other claims), making it distinct from sibling tools like ask_pipeworx or deep_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 says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear when-to-use advice. It does not explicitly mention when not to use or name alternatives, but the specificity of the tool's function implicitly guides appropriate usage among siblings.

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