Nosdeputes Fr

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds valuable behavioral context: default model is free, Anthropic requires a BYO key with direct payment, and returns per-model score/confidence/signals/raw_response plus combined view. 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?

Description is two sentences plus a usage line, front-loading purpose and scoring. It efficiently conveys core functionality, optional features, return format, and use cases without redundancy. Could be slightly more structured (e.g., bullet points) but is already 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 no output schema, description explicitly states return structure: per-model {score, confidence, signals, raw_response} + combined view. It covers required entity, optional models/apiKey/context, and payment aspect. For a simple probe tool with 4 params and high schema coverage, this is sufficiently complete. Minor gaps: no error handling or behavior when models empty.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning: explains 'entity' is the target, 'models' can include 'workers-ai' or 'anthropic', '_apiKey' needed only for Anthropic, and 'context' helps disambiguate. This clarifies parameter usage 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 it probes LLMs to score visibility (0-100) per model, with a specific verb ('probe') and resource ('LLMs for what they know about a business/brand/product/topic'). It distinguishes from siblings like 'entity_profile' and 'scan_competitor_ai_presence' by focusing on multi-model scoring rather than a single profile or competition scan.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') but does not provide explicit when-not-to-use guidance or name specific alternatives among siblings. Usage context is implied rather than direct.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds valuable behavioral context: it routes to 4,396 tools across 1102 sources and returns structured answers with stable citation URIs. This 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 somewhat lengthy but well-structured: begins with preference, then scope, examples, and upgrade paths. Information is front-loaded with the key directive. Still, some sentences could be trimmed without losing content.

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

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

For a broad tool with no output schema, the description adequately explains that it returns a structured answer with citations. It covers the range of domains and provides examples. Minor gap: exact citation format not specified, but acceptable.

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 aliases described. The description adds no further parameter semantics but provides usage examples. Baseline 3 is appropriate since the schema already documents the parameter 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 answers questions about current/historical data from many sources, listing specific domains like SEC filings, FDA drugs, economic stats, etc. It distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, making its purpose concrete.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. Provides clear when-to-use and when-not-to: step up to ask_pipeworx_grounded for hallucination-resistant answers, or deep_research for broad multi-part questions. Examples guide usage.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds critical behavioral details: extraction only from tool result, refusal mechanism with specific reasons, and return shape—all 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 efficient (6 sentences) and front-loaded with purpose. Minor redundancy in listing aliases, but overall well-structured and 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 lack of output schema, the description fully explains return format, refusal cases, and workflow. No gaps for a tool with this complexity and annotation richness.

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 each parameter (including aliases) has a description. The description only repeats 'question in natural language' without adding new semantic details, 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 it is a 'hallucination-resistant answer mode for high-stakes reads' and explicitly distinguishes from ask_pipeworx by emphasizing grounding. The verb 'extracts' and resource 'answer only from tool result' 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?

Provides explicit when-to-use ('quoted, cited, or acted on') and when-not-to-use ('prefer ask_pipeworx for casual lookups') with concrete examples (financial, legal, medical). Also notes the extra cost.

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

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

Description discloses extensive behavioral traits beyond annotations: market resolution, classification, fan-out, evidence packet, response shapes, resolver contract, parent event extraction, news fallback, safety paths (low-confidence, closed markets), wide-spread handling, and cancellation rule parsing. All non-contradictory with annotations (readOnlyHint, idempotentHint).

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

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

While the description is lengthy, it is well-structured with section headings (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and contains no filler. Each sentence adds value. Could be slightly more concise, but organization mitigates verbosity.

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

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

Given no output schema, the description thoroughly covers return shapes, evidence sources, resolver contract, parent event, news fields, safety mechanisms, and cancellation rules. It is complete for an agent to understand what the tool does and how to 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?

All three parameters are described in the schema with 100% coverage. The description adds further context: depth default is 'thorough', market accepts slug/URL/text, include_raw explains summary vs. full payload with size implications. Examples also clarify usage.

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

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

Description explicitly states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and gives usage examples like 'should I bet on X'. This clearly distinguishes it from siblings like polymarket_edges or polymarket_arbitrage, which focus on different aspects.

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

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

Description provides clear usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It does not explicitly state when NOT to use or mention alternative tools, but the context is sufficiently clear for an agent to decide.

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

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

Adds substantial behavioral context beyond annotations: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, result sorting, and citation URI returns. 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 and informative but slightly verbose for a single paragraph. Front-loads query examples effectively, but every sentence earns its place.

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

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

Covers all critical aspects: entity types, data sources, sorting, citation links, and preference over sequential lookups. No output schema, but return format (paired data + citations) is described.

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

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

Schema coverage is 100%, and description enriches both parameters: for 'type' explains data sources, for 'values' specifies tickers/CIKs vs drug names, max 5 items, and example formats.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, using multiple query examples ("Compare X and Y", "X vs Y", etc.) and explicitly distinguishes it from sequential single-pack lookups.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and notes it replaces 8-15 sequential lookups, providing strong when-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds critical behavioral context: account requirement, paid plan for thorough depth, decomposition into facets, parallel routing, and output characteristics (evidence with confidence, source, citation, gaps, never invents). 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 relatively long but well-structured and front-loaded with the most critical information (account requirement and alternative tool). Every sentence serves a purpose, providing details on usage, behavior, and limitations. Slightly verbose but justified by the tool's complexity.

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

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

Given the tool's complexity (multiple data sources, parallel processing, no output schema), the description fully covers the tool's capabilities, output format (findings packet), limitations (gaps for unsupported topics), prerequisites, and expected response time. It leaves no important aspect unexplained.

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 both parameters are documented. The description adds extra value by explaining the depth enum values (quick=3, standard=5, thorough=8) and clarifying that the question parameter accepts broad/multi-part queries. This goes beyond the schema's descriptions.

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

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

The description uses a specific verb ('research') and resource ('1102 STRUCTURED data sources'), clearly distinguishing it from siblings like ask_pipeworx and bet_research. It states that this tool performs multi-source research in one call, which is unique among the siblings.

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

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

The description explicitly states when to use this tool ('broad/multi-part questions over structured data'), when not to use it ('single lookup', 'breaking or colloquial current-news'), and provides alternatives (ask_pipeworx). It also includes prerequisites (account required) and a fallback for unsigned users.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, non-destructive operation. The description adds valuable output context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This goes beyond annotations by describing the return structure and efficiency benefit.

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 concise, with front-loaded purpose and then supporting details. The list of domains is lengthy but provides valuable context for the tool's scope. Each sentence serves a purpose: define, list domain, describe output, give usage advice. No redundancy, though the list could be shortened without losing clarity.

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

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

For a discovery tool with no output schema, the description covers the main aspects: what it does, when to use it, what it returns (with details about schemas and examples), and how it fits into the tool ecosystem. Minor gaps like handling of ambiguous queries or missing results are not addressed, but overall it is sufficiently complete for effective use.

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

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

Input schema has 100% description coverage, so the schema already documents all 6 parameters adequately. The description does not add any new parameter details; it focuses on overall purpose and usage. Baseline score of 3 is appropriate since the schema carries the burden.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb and resource, and distinguishes itself from siblings by positioning as a first-step discovery tool. The extensive list of example domains further clarifies scope.

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

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

The description provides explicit guidance: 'Use when you need to browse, search, look up, or discover what tools exist for:' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells when to use and implies when not to use (when you already know the specific 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 cover readOnly, openWorld, idempotent, and non-destructive hints. The description adds detail on fan-out across multiple sources, soft-fail for patents, sorting of fundamentals, and URI formatting. Could be more explicit about latency or rate limits, but still adds significant value.

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 front-loads with example queries. Every sentence earns its place, but could benefit from bullet points for readability. Still efficient 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?

Despite no output schema, the description explains the full return structure: CIK, company_name, recent_filings with URIs, fundamentals sorted, patents status, news fallback, LEI. Comprehensive for a multi-source profile 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?

Input schema has 100% coverage, but the description reinforces that value must be ticker or CIK, not names, and provides examples. Adds context that type is only 'company' and recommends resolve_entity for name inputs.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company, gives specific example queries, and lists data sources and return fields. It distinguishes from sibling tools like 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?

Explicitly instructs to prefer this tool over chaining single-pack lookups for holistic views, and advises using resolve_entity first if only a name is available. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true, so the description's mention of deletion is consistent but adds limited extra context (e.g., 'clear sensitive data'). 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 concise sentences, front-loaded with purpose, no wasted words. Efficient and well-structured.

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

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

Covers purpose, usage, and sibling context. For a simple delete tool with one param and no output schema, it is mostly complete, though it could mention the idempotent nature (idempotentHint=true) for completeness.

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

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

Schema coverage is 100% with one parameter described. The description adds no new semantic detail beyond 'by key'; baseline of 3 is appropriate.

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

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

The description clearly states the tool deletes a memory by key, using a specific verb and resource. It pairs with 'remember' and 'recall' but does not explicitly differentiate itself as the delete counterpart, leaving slight ambiguity.

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

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

Provides explicit when-to-use scenarios (stale context, task done, clear sensitive data) and mentions pairing with siblings, offering clear guidance on context and alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds that it 'fetches the page, extracts title/description/key links, and emits standard markdown', which goes beyond annotations by explaining the internal process. No contradictions. A 5 would require more detail on edge cases or error handling.

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 well-structured sentences: the first states the core functionality, the second covers context and output format. No wasted words. Front-loaded with the main action.

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

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

Given the simple tool (2 params, no output schema, 100% schema coverage), the description fully covers what the tool does, how it works, and why to use it. No gaps for an agent to understand invocation.

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

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

Schema coverage is 100%, so the description already has the schema's parameter details. The description does not add significant extra meaning beyond restating the schema's 'url' parameter. It mentions 'for any URL' but that's implicit. 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 tool generates a 'production-ready llms.txt file' for a URL, using specific verbs and resource. Although it does not explicitly differentiate from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence', the purpose is distinct enough for an agent to understand. A 5 would require explicit sibling differentiation.

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

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

The description lists three concrete use cases (getting a client's site indexed, drafting own llms.txt, auditing a competitor) which provide clear context for when to use. It does not mention when not to use or alternative tools, but the examples are strong. Lacks explicit exclusion guidance, hence a 4.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds no behavioral traits beyond what annotations provide, such as authentication needs or data source specifics.

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

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

The description is extremely concise and front-loaded, using one short sentence. Every word serves the purpose with no waste.

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

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

Given the presence of an output schema and two parameters, the description could be more complete by specifying that the deputy is from the French National Assembly (NosDéputés). It meets the minimum bar but lacks helpful context.

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

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

The description adds meaning to the slug_or_id parameter by stating it can be a slug or numeric id, which is not fully detailed in the schema (50% coverage). However, the legislature parameter is not mentioned, leaving some lack of clarity.

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

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

The description clearly states the tool retrieves a deputy profile by slug or numeric id. It distinguishes from sibling tools like list_deputies (which lists all deputies) and resolve_entity (generic entity lookup) by specifying the input format.

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

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

No guidance is provided on when to use this tool versus alternatives such as list_deputies, entity_profile, or resolve_entity. The description does not mention prerequisites, context, or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds no further behavioral context (e.g., pagination, permissions). It does not contradict annotations.

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

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

Single sentence, front-loaded with key action and resource, no wasted words.

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

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

For a simple list tool with good annotations and output schema, the description covers its purpose and parameters 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 merely repeats the filter options without adding new semantic information beyond what the schema already provides for parameters.

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

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

The description clearly states 'List sitting deputies' with a specific verb and resource, and it distinguishes from sibling tools like 'get_deputy' (single deputy) and 'list_groups' (lists groups, not deputies).

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

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

The description mentions optional filters but does not provide explicit when-to-use or when-not-to-use guidance, nor does it reference alternative tools among the 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 false. Description adds minimal behavioral context beyond confirming the resource type; 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 very brief, which aids conciseness, but it is under-informative. It could be improved with a more structured phrase without becoming verbose.

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

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

Despite having annotations and an output schema, the description lacks details on how to use the optional parameter (legislature) and what 'political groups' entails. It feels incomplete for effective tool 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 description coverage is 0% and the description does not explain the 'legislature' parameter. It fails to add any semantics beyond what the schema provides, leaving the agent uninformed.

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 'Political groups in the assembly' is a noun phrase that vaguely indicates the resource but lacks a verb. The title 'List Groups' and tool name clarify the action, making purpose somewhat clear but not explicit.

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

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

No guidance on when to use this tool versus alternatives like list_deputies or list_votes. No exclusions or context provided for selection.

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

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

Annotations provide read-only, non-destructive, idempotent hints. Description adds return fields and default behavior (active only), offering additional 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, no wasted words. Purpose, output fields, and usage guidance are clearly front-loaded.

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

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

Complete for a simple listing tool. Describes purpose, output fields, and usage. No gaps given annotations and 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 has 100% coverage and describes the only parameter (include_inactive) well. Description does not add further semantics beyond the schema.

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

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

Clearly states 'List the caller's active subscriptions' with verb 'list' and resource 'subscriptions'. Distinguishes from siblings like subscribe and unsubscribe, and lists return fields.

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: 'review what you're monitoring before adding more or to find an id to cancel'. Provides actionable 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 indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds no extra behavioral context (e.g., sorting, pagination, data freshness). Not contradictory but minimal.

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?

Extremely concise (two words) but lacking substance and structure. Every sentence should earn its place; this is under-specified rather than efficiently 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?

With an output schema present, return values are covered, but the description omits essential operational details like sorting order, pagination defaults, and scope. Incomplete for a list tool.

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

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

Schema coverage is 67%, with descriptions for limit and deputy_slug but not legislature. The description does not add any parameter details beyond the schema, failing to compensate for the missing legislature 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 'Recent recorded votes.' vaguely states verb+resource but lacks specificity about the source, scope, or differentiation from sibling tools like search_interventions. It is clear but not distinctive.

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

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

No guidance on when to use this tool versus alternatives like list_deputies or search_interventions. No exclusions or context for use.

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

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

Discloses rate limiting (5 per day), free usage, and that digests affect roadmap. This adds value beyond annotations, which only indicate non-read-only and non-destructive behavior.

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

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

Concise single paragraph with clear structure: purpose, when-to-use, content guidelines, and behavioral notes. 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?

Complete for a feedback tool: covers input, use cases, best practices, and constraints (rate limit). 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?

Schema coverage is 100%, but description adds usage nuance: don't paste prompts, describe in terms of tools/packs. Also mentions rate limit per identifier.

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

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

The description clearly states the tool's purpose: to tell the Pipeworx team about bugs, missing features, or praise. It lists specific categories and distinguishes from sibling tools (mostly query/research tools) by focusing on feedback submission.

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 (bug, feature/data_gap, praise) and provides guidance on what to include (tool/pack context) and exclude (end-user prompt).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context: data source (CF analytics-engine), no PII, and caching behavior (5min-1h), which goes beyond the annotations.

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

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

The description is well-structured with a clear opening, bullet points for use cases, and technical details. It is informative without being verbose, though some sentences 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?

Despite no output schema, the description explains the return format (top tools, packs, volume) and caching. All parameters are documented, and the annotations cover safety. The description fully prepares the agent for invocation.

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

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

Schema description coverage is 100%, and the description adds meaning to the window parameter by explaining the trade-offs between shorter and longer windows, aiding interpretation beyond the enum values.

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

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

The description uses a specific verb ('Returns') and clearly states the resource ('top tools, top packs, total call volume'). It explicitly distinguishes itself from sibling tools by focusing on trending data aggregated from other agents.

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

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

Three concrete use cases are listed, providing clear context for when to invoke this tool. However, it does not explicitly mention when not to use it or point to alternatives like discover_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?

The description goes far beyond annotations to disclose internal checks: monotonicity assessment, partition_sum check, Jaccard similarity anchor, placeholder filtering, and fill check against live CLOB depth. It explains edge cases like skipped_low_similarity and thin_legs[]. 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 dense and well-structured with mode explanations, but it is relatively long. It could be broken into clearer sections or bullet points for easier consumption. Nonetheless, it is informative and front-loaded with the requirement.

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 and lack of output schema, the description fully explains the output fields (opportunities[], partition_check, fill check details). It covers algorithms, edge cases, and references a sibling tool for custom sizing. 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%, but the description adds substantial meaning: for 'event' it explains child market traversal and partition check; for 'topic' it describes cross-event search and comparator logic. It provides real-world examples and clarifications far beyond the schema alone.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with explicit examples. It differentiates from sibling tools like polymarket_fill_risk and polymarket_edges by mentioning fill check and referencing the sibling for custom sizing.

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

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

Explicitly requires one of 'event' or 'topic' and warns that no args fails. Clearly advises when to use each mode: event for a specific market, topic for cross-event scanning. Explains what cross-event mode catches that single-event misses. Provides context on required parameters and scenarios.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value beyond annotations by detailing internal logic (e.g., caching at KV level, Fed bet exclusion, diagnostic fields). It does not contradict annotations. It could mention auth/rate limits but provides substantial behavioral context.

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

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

The description is very long and dense, running three paragraphs of technical detail. While structured (segments, knobs, output format), it is not concise—many sentences could be streamlined. Important information is front-loaded but the verbosity harms readability.

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

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

Given the tool's complexity (9 parameters, multiple segments, filtering, diagnostics, caching) and no output schema, the description is extremely comprehensive. It explains return values (by_segment, fed_candidates, diagnostics), behavioral details (caching, edge calculation), and filtering logic. 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 description coverage is 100%, so the schema already documents all parameters well. The description adds some extra context for parameters like min_partition_leg_kelly and window, but overall does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes from sibling tools like 'polymarket_arbitrage' by detailing three model segments. The verb 'scan' and resource 'Polymarket markets' plus the unique 'edges' concept make the purpose specific and differentiated.

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

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

The description provides rich context for when to use the tool—for discovering opportunities where model/data disagrees with market price. It explains three segments, filtering knobs, and that Fed bets are excluded. However, it does not explicitly state when not to use or directly compare to sibling tools, slightly reducing clarity.

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, openWorld, idempotent, non-destructive. Description adds detailed behavioral traits: reads snapshots, returns tracked/expired/snapshot_dates arrays, computes decay from daily closes (not intraday), and explains snapshot gaps. 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 and mixes output format with functional explanation. While informative, it could be more structured (e.g., separate sections for args, response, limits). Not optimally concise but front-loaded with key 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, the description fully explains response structure: tracked[], expired[], snapshot_dates[]. Covers edge cases (gaps, TTL, computation from closes). Complete for a read-only telemetry tool.

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

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

Schema already covers both parameters with descriptions. The description adds context: defaults (days 14, window 1wk), max 30 for days, and clarifies window as 'snapshot family'. Adds value beyond schema.

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

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

Description clearly states the tool provides edge persistence and decay telemetry, answering how long an edge existed and if it's shrinking. It distinguishes from sibling polymarket_edges by focusing on time-series and decay analysis.

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

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

Provides context on when to use (comparing fresh vs old edges) and mentions limits like 60-day TTL and snapshot gaps. Does not explicitly state when not to use, but purpose is clear enough to guide selection.

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

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

The description goes beyond the annotations (readOnlyHint, idempotentHint, etc.) by detailing the tool's behavior: walking the ladder, returning specific fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, and a verdict. For basket mode, it describes theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs, and forced_directional_risk. It also warns about the risk of partial fills converting arbs into unhedged positions, providing valuable behavioral context.

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

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

The description is detailed and well-structured with clear sections for each mode, but it is quite long. While every sentence adds value, the length might reduce readability. It could be slightly more concise without losing critical information, but overall it is well-organized and front-loaded with the essential purpose.

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

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

Given the tool's complexity (two modes, multiple return fields, no output schema), the description is remarkably complete. It covers all parameters, explains the return values in detail, and addresses edge cases like thin books and forced directional risk. An agent can fully understand how and when to use this tool based on the description alone.

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

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

With 100% schema description coverage, the baseline is 3, but the description adds significant value by explaining the context and semantics of each parameter in detail. For example, it explains the difference between single-market and basket modes for the market/event parameters, the default and meaning of side in each mode, and how size_usd is interpreted differently (spend vs proceeds vs settlement notional). This far exceeds the schema's simple type/description and provides actionable understanding.

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

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

The description clearly states the tool's purpose as a realizable-vs-theoretical edge check against live order book depth. It explicitly distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by advising use before acting on signals from those tools. The verb+resource structure is specific and unambiguous.

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

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

The description provides explicit guidance on when to use this tool: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. It explains the consequences of not using it (theoretical overround not capturable, partial basket fills become unhedged directional positions), giving clear context for why and when this tool is necessary.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description confirms safety and adds details beyond annotations: safety fields like compatibility_warning, temporal_alignment, skipped_cross counters. 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: it starts with a clear summary, explains modes, response structure, safety fields, and a caution. Every sentence adds value, though it 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 no output schema, the description thoroughly explains return values (venue leg prices, matched spread, safety fields) and edge cases (temporal misalignment, compatibility warnings). It covers all aspects needed for the agent to use the tool correctly.

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

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

Schema coverage is 100% with all three parameters having descriptions. The description adds meaning beyond schema by explaining the two modes, available topic values, how overrides work, and that no parameters are required (implied by 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 states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes from siblings like 'polymarket_arbitrage' by focusing on cross-venue spread. It specifies two modes and explains the response format.

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

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

The description explains when to use each mode (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics return compatibility warnings. It clarifies when spreads are not meaningful (temporal misalignment, non-equivalent bet shapes). Good guidance, but no explicit mention of alternative tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds scope information and the behavior of omitting key to list all. 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 plus a few clauses, front-loaded with primary action. Efficient but could be slightly tighter.

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

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

With no output schema and one optional parameter, the description fully covers behavior (list vs retrieve), scope, and relationship to sibling tools.

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 description adds little beyond what the 'key' parameter description already provides. Baseline 3 applies.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, with specific verb and resource. It distinguishes from sibling tools 'remember' and 'forget' by pairing with them.

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

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

Provides explicit use cases (looking up context like ticker, address, notes) and mentions scoping by identifier. Lacks explicit when-not-to-use or alternative tools, but 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behaviors: it returns source, citation_uri, and raw payload; explains mark_read modifies state (flagging events as read); and mentions polling behavior. However, there is a potential contradiction with readOnlyHint because marking events read is a mutation, though idempotentHint may mitigate that. Overall, the description adds meaningful behavioral context beyond annotations.

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

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

The description is a single well-structured paragraph: it starts with purpose, describes output content, then parameter usage, and ends with a note about polling and alternative access. No fluff; every sentence adds value. Slightly longer than necessary, but efficient.

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

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

Given 5 optional parameters, no output schema, and annotations present, the description covers the tool's input, output content, key parameter behaviors, and usage context. It lacks explanation of 'evaluator' or 'subscription feed', but is otherwise complete for an agent to understand how to invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that returned alerts carry source, citation_uri, and raw payload (not in schema), and provides context for mark_read (flags events as read). It does not cover unread_only in description, but overall it enriches parameter understanding beyond the schema's brief 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 pulls fired events from a subscription feed, using the verb 'Pull' and specifying the resource. It also distinguishes itself from sibling tools by describing its function (fetching recent alerts) and mentioning an alternative access method, making its purpose 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?

The description provides usage guidance on filtering by type and since, setting mark_read, and notes that polling works fine. It also points to an alternative API endpoint for scripts/dashboards. While it doesn't explicitly state when not to use this tool, it sufficiently guides the agent on how to use it effectively.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable operational details: fan-out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, and return structure. No contradictions.

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

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

The description is well-structured with query examples upfront, then fan-out details, parameter notes, return structure, and sibling differentiation. Every sentence adds value, though slightly lengthy.

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, fallbacks, soft-fail, no output schema), the description is remarkably complete. It covers all essential behavioral and usage aspects.

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

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

Schema coverage is 100%, and the description enhances meaning: explains 'since' accepts ISO or relative format with examples, 'value' accepts ticker or CIK, and 'type' is restricted to 'company'. Adds clarity beyond the schema.

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

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

The description clearly states the tool's purpose: a 'change feed for a company in the last N days/weeks/months in ONE parallel call'. It provides multiple query examples and distinguishes from the sibling 'entity_profile' 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 provides when-to-use versus when-not-to-use: 'Use entity_profile instead when you want the static profile...'. Also explains the tool fans out to multiple sources with fallback behavior.

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 non-destructive, idempotent. Description adds persistence details (authenticated vs anonymous, 24-hour TTL). 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?

Three sentences with no waste. Front-loaded with purpose, then usage, then retention policy. 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 needed; description covers storage, retrieval pairing, and scope. Complete for a key-value store 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 has 100% coverage with descriptive examples. Description adds scoping context ('by your identifier') and generalizes value type.

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?

Specific verb 'Save data' with resource 'later reuse'. Examples and distinction from siblings recall/forget give clear unique purpose.

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 you discover something worth carrying forward') and pairs with recall/forget. Also covers session persistence 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?

Beyond annotations (readOnly, idempotent), the description reveals internal cascading through multiple endpoints and details return values including citation URIs, adding significant context.

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

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

Compact and well-structured with front-loaded examples and clear details. Every sentence adds value with no wasted words.

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

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

Despite no output schema, the description fully explains return values and internal behavior, making it complete for the tool's purpose.

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

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

With 100% schema coverage, the description enriches parameters by providing specific examples (e.g., 'AAPL' for ticker, 'ozempic' for drug) and explaining auto-disambiguation for companies.

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 user-spoken names to canonical/official identifiers with specific examples (ticker, CIK, RxCUI). It distinguishes from siblings by being the primary tool for name-to-ID lookup.

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 FIRST whenever you have a name but need an ID' and describes supported types and outputs. Could be more explicit about when not to use, but the guidance is strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as safe. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks results, and surfaces most/least recognized. This goes beyond annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the action and outcome. No redundant words. Every sentence adds value: mechanism, use case, and return format.

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

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

For a tool with 4 parameters and no output schema, the description fully covers the expected return (ranked list with score, confidence, signal density), internal workflow (calls ai_visibility_check), and constraints (2-8 entities). No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that the first entity is treated as the 'subject' and the rest as competitors, and that context disambiguates common names. This enriches the parameter semantics beyond the schema.

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

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

The description clearly states the tool's purpose: compare AI visibility across multiple entities side-by-side, using ai_visibility_check probes, ranking by score. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic). The verb 'compare' and resource 'AI visibility' 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?

The description explicitly states it's useful for competitive AI-marketing audits and provides a concrete example question. It implies when to use but does not explicitly state when not to use or mention alternatives like ai_visibility_check for single entities. However, the context is clear enough for an agent to infer appropriate 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), description details external service fan-out, partial failure behavior ('degrade gracefully'), latency warning ('first measurement on new version can take 5-30s'), and lists return fields. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the core purpose. It is slightly wordy but every sentence adds useful information (usage, ecosystem, behavior, return values). Could be tightened but remains 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 (aggregating two external APIs, no output schema), the description thoroughly covers what is returned (summary fields, advisory detail, links, alternatives), limitations (NPM only, bundlephobia timeout), and graceful degradation. Provides sufficient context for correct invocation.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by explaining scoped packages acceptance for 'package' and default behavior for 'version' (defaults to latest). This enriches schema but does not introduce entirely new 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 it's a composite check for deciding to add an npm package, aggregating data from deps.dev and bundlephobia. It uses a specific verb ('scan_dependency') and defines the resource as 'npm package for project evaluation'. This distinguishes it from unrelated siblings.

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

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

Explicitly advises use when an agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Also specifies ecosystem limitation ('NPM ecosystem only in v1') and directs broader queries to 'deps.dev:version directly.' Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds no further behavioral disclosure (e.g., result format, pagination). It aligns with annotations but does not enhance transparency beyond them.

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

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

The description is a single, front-loaded sentence with no unnecessary words. Every word earns its place. It is optimally concise for a search 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?

With 6 parameters and an output schema, the description is minimal. It does not explain the nature of 'debate contributions' or provide usage examples. While annotations cover safety and the schema covers params, the description lacks completeness about tool behavior and context.

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

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

Schema description coverage is 67% (4 of 6 params have descriptions). The description itself adds no parameter info; it relies on the schema. For params with descriptions, the schema suffices; for query and legislature without descriptions, the description does not compensate. Overall, minimal added 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 is a single, clear statement: 'Full-text search across debate contributions.' It specifies the verb 'search', the resource 'debate contributions', and the type 'full-text'. Among sibling tools like search_questions and search_within, this clearly differentiates its scope.

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

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

The description provides no guidance on when to use this tool versus alternatives (e.g., search_within, search_questions). There is no mention of when not to use it or any prerequisites. Explicit usage context is absent.

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 as read-only, idempotent, and non-destructive. The description adds context about returned fields but no additional behavioral traits beyond what annotations provide. 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 with no wasted words. Front-loaded with the core action (Search) and essential details. Perfect length for quick understanding.

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

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

With an output schema present, return values are documented. The description covers main filters and source, but misses explaining limit and legislature parameters. Otherwise complete for a search 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 only 20%, leaving 4 of 5 parameters undocumented. The description explains type, query, and deputy_slug but omits limit and legislature. Examples partially compensate but parameter semantics are insufficient.

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

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

The description clearly states it searches questions submitted by French Assemblée nationale deputies, specifies filters (query, deputy slug, type), and lists returned fields. However, it does not explicitly differentiate from sibling tools like search_interventions or suggest_questions.

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

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

The description implies usage context (searching questions) but provides no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. Sibling tools exist but are not referenced.

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 safety traits (readOnly, openWorld, idempotent, non-destructive). The description adds significant behavioral details: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), character limit (200K), truncation with flagging, and return fields (character offsets, similarity scores). This fully compensates for the missing output schema.

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

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

The description is three concise sentences, front-loaded with the core functionality, and efficiently packs all necessary behavioral details without 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 lack of output schema, the description adequately explains the return format (top-N passages with character offsets and similarity scores), the limitation (200K chars, truncated and flagged), and the intended usage. No critical gaps for a semantic search 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%, so the baseline is 3. The description does not add meaning beyond the schema's own descriptions; for example, the query parameter description is identical in both. No additional value is provided for parameter usage or format.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifying inputs (text and query) and outputs (passages with offsets and scores). It distinguishes itself by pairing with a sibling tool (ask_pipeworx_grounded) and explaining when it's useful.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also provides an alternative workflow, describing how it pairs with ask_pipeworx_grounded, giving clear usage context and 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 discloses key behavioral traits: requires a Pipeworx OAuth account, returns subscription ID, subscription persistence limitations, delivery channel details (email/SMS constraints, webhook signing, auto-disable after failures). Annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false) are consistent with these disclosures.

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 yet front-loaded with the core purpose. It uses clear formatting (bullets, parentheses) but may be slightly verbose. Every sentence adds value, though some 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?

Despite no output schema, the description mentions the return value (subscription ID). It covers all complex nested parameters, delivery channels with constraints, and auth requirements. The tool's complexity is fully addressed.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond schema: explains item codes for sec_8k, provides examples for each type, details delivery constraints (phone verification, daily caps, webhook signing). This enables correct parameter construction.

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 verb ('Create'), resource ('a proactive monitoring subscription to a live-data event stream'), and distinguishes it from siblings like list_subscriptions, unsubscribe, and recent_alerts. It explicitly lists supported types and delivery methods.

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

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

The description provides clear context on when to use the tool (setting up subscriptions) and details on types and delivery options. It does not explicitly state when not to use it or name alternatives, but the sibling list implies other subscription-related tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds value by detailing the behavior: returns category-bucketed example questions with exact tool+argument shape from the live catalog, and nothing contradicts the annotations.

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

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

The description is fairly long but every sentence serves a purpose. It front-loads the main purpose and alternate phrasings, then details the output and usage. Minor redundancy could be trimmed, but it remains informative and structured.

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

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

Given the tool's simplicity (1 optional parameter, no output schema, rich annotations), the description covers all necessary aspects: when to use, what it returns, how to use arguments, and the catalog scope. It is fully complete 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%, but the description adds meaning beyond the schema by explaining the topic parameter's examples ('finance', 'pharma', etc.) and the effect of omitting it (cross-category spread). This provides useful context.

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

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

The description clearly states the tool is an onboarding entry point that returns categorized example questions. The verb 'suggest questions' is precise, and the description distinguishes it from siblings like 'search_questions' and 'ask_pipeworx' by specifying its unique role.

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

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

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

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

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

Description adds behavioral context beyond annotations: deactivation (not deletion) preserves history, ownership enforcement. Annotations already indicate non-destructive and idempotent, but description gives clear semantic meaning.

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

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

Two sentences, no fluff, front-loaded with purpose. Every sentence adds value. Perfectly 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?

For a simple tool with one parameter and no output schema, the description covers purpose, side effects, ownership, and relationship to sibling tool 'recent_alerts'. Complete.

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

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

Schema coverage is 100%, so description adds minimal value. Description mentions 'by id' but schema already defines 'id' as subscription uuid. 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?

Description clearly states verb 'Cancel' and resource 'subscription by id'. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying it is for cancellation and ownership enforcement.

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 ownership enforcement (can only cancel own subscriptions) and explains the soft-deactivation behavior with historical events preserved via 'recent_alerts'. Does not explicitly mention when not to use, but context is sufficient.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds details about return values (verdict, structured form, citation, percent delta) and efficiency gains, enhancing transparency beyond annotations.

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

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

The description is efficient, front-loaded with examples and purpose. It is slightly verbose in listing examples but remains well-structured and relevant.

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 NLP claim verification and a single parameter with no output schema, the description adequately covers purpose, scope, return types, and limitations (v1 for US financial claims).

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 a clear description. The tool description adds context about the type of claims supported but doesn't significantly augment the parameter meaning beyond 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 states the tool verifies natural-language claims against authoritative sources, with specific examples and scope. It distinguishes itself from sibling tools by its unique function.

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

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

Explicitly says 'Use whenever the agent needs to check factual correctness' and describes what it replaces. Does not explicitly state when not to use, but the scope is implied.

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