Close Crm

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds behavioral context: it probes multiple LLMs, requires API key for Anthropic, returns per-model scores with confidence and raw response. This adds value 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?

4 sentences with no waste. Front-loaded with the main action and key details. Efficient and informative.

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

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

Even without output schema, the description explains the return structure (per-model score, confidence, signals, raw_response + combined view). It covers prerequisite (_apiKey), default behavior, and use cases. Complete for a probing tool.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds semantic value: explains default model behavior, when _apiKey is needed, and how the context parameter helps disambiguate. This goes beyond the schema baseline of 3.

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

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

The description clearly states it probes LLMs for knowledge about a business and scores visibility 0-100. This is a specific verb+resource combination that distinguishes it from sibling tools like ask_pipeworx that are for asking about Pipeworx specifically.

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 default model (Workers AI free), optional Anthropic probing with _apiKey, and use cases (AI-marketing audits, pre-launch checks). It does not explicitly say when not to use or list alternatives, but provides clear context for when it's appropriate.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond that: it routes to 5,708 tools, fills arguments automatically, returns stable pipeworx:// citation URIs, and is described as 'one fast call' that 'works on every tier.' This is rich context, though it does not mention failure modes or rate limits.

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

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

The description is long but every section earns its place: priority flag, supported domains, examples, sibling routing, and exclusions. It is front-loaded with the most important direction ('PREFER OVER WEB SEARCH'). It could be tightened slightly, but the density of actionable guidance justifies the length.

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

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

For a complex router tool with no output schema, the description explains the return format ('structured answer with stable pipeworx:// citation URIs') and the scope of sources (1,494 verified sources). It also addresses tier compatibility and speed. It does not describe potential ambiguous-question handling or response length limits, but the provided context is sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema already documents the 'question' parameter and its aliases. The description adds example phrasings ('what is', 'look up', 'find', 'get the latest') that are useful for choosing how to phrase a query, but it does not provide deeper semantics beyond what the schema already offers.

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

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

The description uses a specific verb ('routes the question to the right one of 5,708 tools') and a clear resource ('Pipeworx'), explaining exactly what the tool does. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, so an agent can tell them apart without inspecting their schemas.

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

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

The description gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when-not-to-use guidance ('Step up only when needed' for grounded or deep_research). It also provides concrete trigger phrases and examples, leaving no ambiguity about when to select this tool.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: this is the experimental edge, currently identical to ask_pipeworx, has no fallback, and is a fully working router. This level of honesty and detail exceeds what annotations alone provide.

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

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

The description is longer than average but every sentence earns its place by clarifying beta status, current behavior, and usage intent. Slight redundancy in stating both 'identical universal router' and 'matches ask_pipeworx exactly' keeps the meaning unambiguous, but the structure is front-loaded and coherent.

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

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

Given the absence of an output schema, the description compensates by stating the response shape is identical to ask_pipeworx. It covers what the tool is, its relationship to the stable version, its current runtime state, and that it is a full router. Nothing essential for invoking it or deciding between it and ask_pipeworx is missing.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for 'question'. The description does not add parameter-level detail beyond noting the tool uses the same arguments as ask_pipeworx, so the schema carries the burden adequately and the description neither helps nor hurts.

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

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

The description clearly identifies this as the beta variant of ask_pipeworx, an identical universal router over 5,708 tools with the same arguments and response shape. It distinguishes itself from the stable ask_pipeworx by its live candidate routing improvements, and the current no-candidate state is 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?

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. This gives the agent a clear selection rule versus its primary sibling.

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

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

Annotations already establish read-only/open-world/idempotent behavior, and the description adds valuable beyond that: refusal contract with exact refusal_reason values, evidence extraction rule, and the extra LLM call cost. 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?

Three sentences are dense but each earns its place: mode and routing, return/refusal contract, then when to use and cost trade-off. Key caveats are 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?

Though there is no output schema, the description fully specifies the success and refusal shapes, making the return contract explicit. It resolves ambiguity vs ask_pipeworx and ask_pipeworx_beta and covers the extra-call cost, so an agent has the information needed to invoke correctly.

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

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

Schema has 100% coverage; the description points to natural language questions and alias handling without adding much parameter-level detail beyond the schema. This is the baseline expected when the schema fully documents the single required parameter.

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

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

The description opens by naming the tool as a 'hallucination-resistant answer mode' and specifies exact behavior: route across 5,708 tools, fill arguments, fetch data, extract answer only from tool result. It differentiates from ask_pipeworx by emphasizing grounded extraction with evidence and explicit refusals.

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

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

It gives explicit when-to-use conditions: 'whenever an answer will be quoted, cited, or acted on' and where invention is unacceptable. It also states the trade-off ('costs one extra LLM call') and directs casual lookups to ask_pipeworx, an explicit alternative.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description goes far beyond, detailing resolver contracts, parent event extraction, news fields, safety mechanisms for low-confidence matches, closed market handling, wide spread detection, and cancellation rules. 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 long but well-structured with sections and front-loaded purpose. Almost every sentence adds useful information. While verbose, it effectively organizes complex details without being wasteful.

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

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

Given the tool's complexity, 3 parameters, and no output schema, the description covers all critical aspects: input types, resolution confidence, parent events, news fields, safety, cancellation rules, and response shapes. It is comprehensive for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning: depth (quick vs. thorough), market (slug/URL/question), and include_raw (when to use false vs. true, with response size context). This adds value beyond the schema.

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

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

The description explicitly states the tool researches a Polymarket bet by pulling relevant Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + comparison). While it doesn't explicitly differentiate from sibling tools like polymarket_edges, its unique function is clearly defined.

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 use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and includes detailed fan-out examples. It does not explicitly state when not to use this tool vs. alternatives, but the context is strong.

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

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

Annotations already declare readOnlyHint=true, so no mutation. Description adds return details, which is useful beyond annotations. 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 clear action and list of returned fields. Front-loaded and efficient.

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

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

No output schema, so description explains return values comprehensively. Covers purpose, input, and output completely.

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 only reinforces the lead_id format. No additional meaning beyond the schema, so baseline score.

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 'Get a single lead by its Close lead ID' with format specification. It lists the full detail returned, distinguishing it from sibling tools like close_search_leads.

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

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

It explicitly says when to use (given a lead ID) and implies context. Does not state exclusions or alternatives, but sibling names indicate different purposes.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds response structure details (data array with fields, has_more, total_results) and pagination behavior, complementing annotations without contradiction.

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

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

Three sentences, front-loaded with main purpose, no redundant text. Efficiently conveys key information.

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

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

Covers required parameters, pagination, and response fields. Lacks output schema but description compensates with field listing. Could mention _apiKey but schema covers it.

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

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

Schema covers 100% of parameters with descriptions. The description reinforces lead_id and pagination usage but does not add significant new semantic detail beyond what the schema provides.

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

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

The description clearly states 'List activities for a lead' with specific types (calls, emails, notes, SMS, meetings, status changes). It distinguishes from sibling tools like close_list_contacts and close_list_opportunities by targeting lead activity timelines.

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

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

The description specifies required lead_id and pagination with _limit/_skip, giving clear usage context. It lacks explicit when-not-to-use or alternative tools, but the sibling list implies differentiation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds beyond that by detailing the return structure (data array with fields, pagination metadata), which is valuable for understanding output.

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 front-loaded sentences covering action, return structure, filtering, and pagination. No superfluous words; every sentence earns its place.

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

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

Given no output schema, the description fully explains the return format including field names and pagination fields. It covers necessary parameters and usage context, making it complete 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 100% for all 4 parameters. Description reiterates lead_id and pagination parameters but adds no new semantic meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

Clearly states 'List contacts (people) in Close' and specifies return fields. Distinguishes from sibling tools like close_get_lead and close_list_activities by naming the resource and providing specific output details.

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

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

Provides clear context for usage: filtering by lead_id and pagination with _limit/_skip. While it doesn't explicitly exclude alternatives, the guidance is sufficient for proper invocation.

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

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

Annotations already declare readOnly, idempotent, non-destructive; the description adds value by detailing the return format (data array with fields, has_more, total_results) and pagination behavior, going beyond annotation info.

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 filler. First sentence front-loads purpose and return structure; second covers filtering and pagination. Every sentence earns its place.

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

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

Given no output schema, the description adequately explains return structure, scoping, and pagination. For a simple list tool, it covers key behaviors; minor omissions like ordering or error handling prevent a 5.

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

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

The input schema has 100% coverage with descriptions for all parameters. The description adds minimal extra meaning beyond the schema, primarily tying together pagination and scoping usage, so baseline score of 3 is appropriate.

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

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

The description starts with a clear verb+resource pair ('List opportunities') and distinguishes from sibling Close list tools (activities, contacts) by specifying 'opportunities (pipeline deals)'.

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 for when to use lead_id (scope to one lead) vs. omit (list organization-wide) and explains pagination with _limit/_skip. However, it lacks an explicit when-not-to-use or comparison with search 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 provide readOnlyHint, idempotentHint, and destructiveHint, so the description's burden is lower. It adds value by detailing the specific data returned (user, name, email, organizations) and the purpose (verification, context discovery), which is beyond what annotations convey. No contradictions.

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

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

The description is two sentences long, with the action and primary purpose stated first. Every sentence is essential—no redundancy or filler. It is optimally concise for such a simple tool.

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

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

Given the tool's low complexity, single parameter, and lack of output schema, the description fully covers what the agent needs: it names the returned fields (user ID, name, email, organizations) and the use case (verify key, discover context). Annotations handle the behavioral safety profile. 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 does not add any meaning about the _apiKey parameter beyond what the schema already provides ('Close API key (Settings → API Keys)'). Thus, no extra value is contributed.

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 gets the current Close user and organization for the supplied API key, specifying the verb 'get' and the resource. It also lists the return fields (user ID, name, email, organizations), making the purpose unmistakable. No sibling tool serves the same function, so differentiation is inherent.

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

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

The description explicitly advises using the tool to verify the API key works and discover organization context, which is a direct and actionable usage guideline. It does not mention when not to use or list alternatives, but given that no sibling provides equivalent functionality, the guidance is sufficient.

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

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

The description adds value beyond annotations by explaining the return structure (data, has_more, total_results), pagination limits, and default _limit. Annotations already indicate read-only, idempotent, non-destructive behavior, and the description is consistent.

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

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

The description is one concise paragraph with clear structure, examples, and no redundant information. It could be slightly more structured 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?

Despite no output schema, the description sufficiently explains the return fields and pagination. It covers usage, query syntax, and parameter semantics, leaving no major gaps for this tool's complexity.

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

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

With 100% schema coverage, the baseline is 3. The description adds meaning by providing query syntax examples, explaining the effect of omitting 'query', and clarifying pagination behavior for _limit and _skip.

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 or lists leads in Close using the Close query language, with specific examples. It distinguishes from siblings like close_get_lead by focusing on search and list functionality.

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

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

The description provides explicit guidance on when to include a query vs. omitting it to list all leads, and how to paginate. However, it does not explicitly compare to alternative tools like close_get_lead or close_list_contacts.

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, etc. The description adds valuable behavioral details: data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradictions.

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

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

Front-loaded with example queries, then details data sources and behaviors. Slightly verbose but every sentence adds value. Could be tightened slightly but still effective.

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

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

Given the tool's complexity and good annotation support, the description covers purpose, usage, data sources, edge cases (fiscal years), sorting, and return format (paired data + citation URIs). No output schema but description is sufficient.

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

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

Schema coverage is 100% but description adds meaning: explains what each type returns (revenue/net income/cash/debt for companies; adverse events/approvals/trials for drugs) and how to specify values (tickers, names). Provides examples beyond the schema.

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

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

The description uses specific verbs ('compare', 'side-by-side comparison') and clearly identifies the resource (companies or drugs with specific data sources). It distinguishes from siblings like entity_profile by emphasizing multi-entity comparison in one call.

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 'ALWAYS PREFER over sequential single-pack lookups' and provides example query patterns. Does not explicitly list when not to use, but the context is clear and alternatives are implied by sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description adds substantial behavioral context: account/pricing requirements, latency expectations, gap[] honesty (never invented), citation URI fetchability conditions, and semantic excerpting behavior. 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 dense and long, but it is front-loaded with the account requirement and alternative routing. Each sentence carries operational value, though the text could benefit from structural formatting for quicker scanning.

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

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

With no output schema, the description compensates thoroughly by specifying the return packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, hop field), the gaps[] and contradictions[] arrays, and expected latency ranges. It also covers auth, pricing, and failure modes, making it complete for an agent deciding to call 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 the schema already documents both parameters. The description adds value by clarifying that 'standard' is the default, 'thorough' requires a paid plan, and how each depth level maps to hops, gap recovery, and contradiction scanning.

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?

States a specific verb ('research') and resource ('Pipeworx's 1494 structured data sources'), explains the decomposition-and-parallel-routing mechanics, and explicitly distinguishes the tool from open-web search and ask_pipeworx. An agent can immediately understand what this tool does and what it does not.

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 'Best for broad/multi-part questions over structured data' and directs users to ask_pipeworx for single lookups, breaking current news, and when not signed in. It names the alternative and the conditions that select it, leaving nothing to inference.

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, idempotentHint=true, destructiveHint=false. The description adds behavioral details about return format (top-N tools with schemas and curated examples, ready to call) 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?

Well-structured with front-loaded purpose, but includes a somewhat lengthy list of domains that could be trimmed without loss of 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?

Covers purpose, return format, and usage guidance. Missing explicit mention of default limit (but schema covers it) and error handling, but adequate for a discovery tool with good annotations and schema coverage.

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

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

Schema coverage is 100%, so schema already describes all 6 parameters. The description adds examples and clarifies aliases, but does not significantly enhance meaning beyond schema.

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

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

The description clearly states 'Find tools by describing the data or task,' using a specific verb and resource. It distinguishes this meta-tool from sibling tools (which are specific domain tools) by positioning it as a discovery tool to be called first.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' providing clear when-to-use guidance and 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 safe reading (readOnlyHint, idempotentHint, not destructive). The description adds significant behavioral context: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields, and notes that patent data 'soft-fails until reactivated.' No contradiction with annotations.

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

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

The description is a single dense paragraph covering many details. While comprehensive, it could be better structured (e.g., bullet points or separate sections). It front-loads the purpose with examples, which is good, but the length reduces scannability.

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

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

Despite lacking an output schema, the description thoroughly explains the return data: CIK, company name, recent filings with URIs, fundamentals, patents, news, and LEI. It covers input constraints, data sources, and fallback behavior, making the tool's behavior fully understandable.

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% (both parameters described in schema). The description adds meaning beyond schema by specifying that 'type' only supports 'company' and 'value' accepts ticker or zero-padded CIK, and clarifying what formats are valid. This provides practical usage hints.

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 in ONE parallel call.' It lists specific query examples and distinguishes itself from chaining single-pack lookups by saying 'ALWAYS PREFER over chaining.' This makes the purpose unmistakable.

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

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

The description explicitly says when to use this tool: 'when the user asks for a holistic view.' It also tells when not to use it: if only a name is provided, stating 'names not supported (use resolve_entity first if you only have a name).' This provides clear decision-making 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 provide destructiveHint=true and idempotentHint=true. The description adds behavioral context by explaining the purpose (clearing sensitive data) and pairing, which goes beyond annotations.

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

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

Three concise sentences: action, usage conditions, and pairing advice. No unnecessary words.

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

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

For a simple delete tool with one parameter, the description covers purpose, usage, and related tools. It doesn't describe return behavior, but annotations cover idempotency and destructiveness.

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 the schema already describing the 'key' parameter. The description only restates 'by key' without additional semantics, meeting the baseline.

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

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

The description clearly states 'Delete a previously stored memory by key,' specifying the verb and resource. It distinguishes from siblings by mentioning pairing with 'remember and recall' and gives concrete usage scenarios.

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

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

It explicitly says when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' While it doesn't state when not to use, it provides clear context and pairing hints.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds context by explaining the fetching and extraction process, which aligns with annotations. 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 a single paragraph of about 60 words, front-loaded with the main action. It is efficient, though a bit redundant ('production-ready llms.txt file'). No wasted sentences.

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

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

With two parameters and no output schema, the description explains the output format and use cases, providing sufficient context for a straightforward generation 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 for the 'url' parameter with examples but does not elaborate on 'max_links' beyond what's in the schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, explaining the purpose for AI crawlers, the process (fetches page, extracts info, emits markdown), and output format. No confusion with sibling tools.

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

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

The description explicitly lists use cases: getting a client's site indexed, drafting for own project, or auditing competitor crawl. While it doesn't state when not to use, the guidance is clear and actionable.

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, idempotentHint, destructiveHint false, so the description builds on that by noting the scope ('caller's subscriptions') and the return structure. It adds value beyond annotations without contradiction.

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

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

Two sentences with no wasted words. Clearly states what it does, what it returns, and when to use it. 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?

For a simple read-only tool with one optional parameter and rich annotations, the description covers all essential aspects: purpose, return values, usage context, and scope. No missing critical information.

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

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

Schema coverage is 100% with the single parameter already fully described in the schema. The description does not add any further clarification on the parameter, 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?

Describes the tool as listing the caller's active subscriptions, specifying the resource and action. It also indicates the returned fields and provides usage context, making the purpose unmistakable. While sibling tools subscribe/unsubscribe exist, the description clearly distinguishes by focusing on listing.

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: 'review what you're monitoring before adding more or to find an id to cancel.' This provides clear context. However, it does not mention when not to use or alternative tools, though the sibling context implies differentiation.

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

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

The annotations only say readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the description carries the burden of behavioral detail. It discloses claim_token mechanics for anonymous follow-up, daily rate limits, quota exemption, and the fact that feedback is read by a team and influences roadmap. This goes well beyond the annotations and gives the agent a clear expectation of side effects and constraints.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose, then logically covers use cases, exclusions, follow-up mechanics, rate limits, and cost. While long, the length is justified by the tool's nuanced edge cases and the absence of structured annotations.

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

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

With no output schema, the description must explain return behavior, and it does: filing without an account returns a claim_token, and passing it back later returns status and resolution details. It also covers scope restrictions, message guidance, rate limits, and commercial terms, making it fully self-contained for a low-complexity feedback 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?

Although the schema already covers 100% of parameters, the description adds substantial semantic value. It explains how to pass claim_token back to read a prior report, instructs users to frame issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, and clarifies the context field's purpose. This enhances the schema rather than merely repeating it.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly distinguishes the tool from siblings like ask_pipeworx and discover_tools, marking it as a feedback/reporting channel rather than an information retrieval tool.

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

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

The description explicitly enumerates when to use it: bug reports, feature/data_gap requests, praise, and 'other.' It also gives a clear exclusion: only for tools served by this Pipeworx connection, directing users to file elsewhere for other MCP servers. This is strong when/when-not guidance with actionable 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?

Description adds details beyond annotations: data source (CF analytics-engine), no PII, caching strategy (5min-1h). No contradictions with annotations.

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

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

Concise, front-loaded with main output, then use cases, then technical details. Every sentence adds value.

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

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

For a simple tool (1 optional param, no output schema, non-destructive), the description is complete: output, usage, source, caching, privacy.

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

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

Schema covers window parameter with enum and description. Description adds nuance about short vs long windows. Both complement each other.

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

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

Clearly states the tool returns top tools, packs, and call volume over a window. Provides specific use cases (discovering hot data, confirming canonical choice, alignment). Differentiates from siblings by focusing on trending analytics.

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

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

Explicitly lists three use cases. Notes caching behavior. Does not explicitly mention when not to use or alternatives, but the context is clear given sibling tools.

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

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

Description adds substantial behavioral context beyond annotations: explains partition_check, Jaccard similarity filter, placeholder fraction check, fill check against live depth. No contradiction with annotations (readOnlyHint, openWorldHint, etc.).

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

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

Description is well-structured with headings and front-loaded purpose. Each section adds value, though slightly verbose. Could be tightened 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?

Given complexity (multiple modes, fill check, filters) and no output schema, the description covers response structure (opportunities[], partition_check fields, fill check results) and processing logic, making it fully actionable for correct invocation.

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

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

Schema coverage is 100%, and the description enriches parameter meanings: for `event` provides examples and recommends usage for specific markets; for `topic` explains cross-event scanning and gives seed question examples. Adds context beyond schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) with specific examples, differentiating from sibling tools like polymarket_edges.

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

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

Gives clear context for each mode: event recommended for a specific market, topic for cross-event scanning. Provides examples and usage hints (e.g., `event` recommended). References polymarket_fill_risk for custom sizing, but does not explicitly exclude other sibling arbitrage 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 (readOnlyHint, idempotentHint) are consistent with description. The description adds extensive behavioral details: caching at KV level, response structure including diagnostics, model family mechanics, and edge calculation. No contradictions.

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

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

The description is long and technical, with deep dives into model families. While front-loaded with purpose, it lacks conciseness. Some details could be condensed, but length is somewhat justified by 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 9 parameters, no output schema, and complex behavior (three segments, diagnostics), the description thoroughly covers output structure, caching, error explanations, and edge cases. It fully compensates for missing output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context on parameter interactions (e.g., tradeable-edge knobs) and rationales (e.g., min_partition_leg_kelly's purpose), providing meaningful 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 starts with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price,' using specific verbs like 'scan' and 'return.' It clearly distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by stating its discovery 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 states 'Built for "what should I bet on today"' and hints at alternatives like polymarket_arbitrage. It also explains that Fed bets are excluded from ranking. However, it lacks explicit 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 safe, read-only behavior. The description adds substantial behavioral details: how decay is computed (daily closes, not intraday), what output fields mean, and the snapshot mechanism with gaps. 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 informative but somewhat dense. It front-loads the purpose effectively but could benefit from clearer sectioning. Still concise for the amount of detail provided.

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

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

Without an output schema, the description fully explains the output structure (tracked, expired, snapshot_dates) and covers behavioral nuances, limits, and edge cases. Complete for a two-parameter tool with no output schema.

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

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

Schema has 100% coverage, so baseline is 3. The description adds context about default values, clamps, and window families ('24hr | 1wk | 1mo'), providing additional meaning beyond schema descriptions.

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

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

The description clearly states it tracks edge persistence and decay, answering 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis and trend detection.

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

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

The description provides explicit context for when to use this tool, contrasting fresh vs. old edges. It mentions limits (60-day TTL) but doesn't explicitly list when not to use or alternatives.

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

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

The description details what the tool returns (top_of_book, vwap_fill_price, slippage_pp, etc.) and warns about forced directional risk. Annotations (readOnlyHint, idempotentHint) are consistent and the description adds 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?

Every sentence is informative and front-loaded with the core purpose. Despite length, there is no redundancy; it efficiently packs mode descriptions, parameter usage, and risk warnings into a compact structure.

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

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

The tool has no output schema, but the description thoroughly lists all key return fields and explains both operational modes. Given the complexity (two modes, multiple return fields), it covers essential information completely.

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

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

Schema coverage is 100%, and the description adds significant meaning: explains single-market vs basket modes, default behavior for side, and nuanced interpretation of size_usd (spend vs target proceeds vs settlement notional).

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and explicitly distinguishes itself from siblings like 'polymarket_arbitrage' and 'polymarket_edges' by telling when to use it before those tools.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains risks of partial fills and thin books, making it clear when and why to use this tool.

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

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

The description goes far beyond the readOnly/idempotent annotations, disclosing compatibility_warning and compatibility_codes, the never-pair-unknown-legs rule, skipped_cross_type/skipped_cross_subtype counters, temporal_alignment, and low_confidence_pairs. It also explicitly cautions that pre-mapped does not mean tradeable. This is exemplary behavioral disclosure.

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

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

The description is long, but every sentence earns its place given the tool's complexity. It is front-loaded with the core purpose, then organized into modes, response shape, safety fields, codes, and skipped-comparison behavior. The density is justified by the number of caveats an agent must understand to interpret results correctly.

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

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

With no output schema, the description carries the burden of explaining the response, and it does so thoroughly: prices, top_spreads_pp, compatibility fields, codes, skipped counters, and temporal alignment. The main gap is that all parameters are optional in the schema, yet the description does not explicitly state that at least one mode (topic or explicit identifiers) must be provided for a meaningful call.

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 already documented in the schema, and the description adds meaningful behavioral semantics: `topic` triggers pre-mapped retrieval, while `kalshi_event_ticker` and `polymarket_event_slug` override the mapped side for custom pairings. This goes beyond the schema descriptions by clarifying how the parameters interact.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, and the two input modes make its purpose concrete. It does not explicitly differentiate itself from sibling tools like polymarket_arbitrage, so the distinction is clear by content but not by direct contrast.

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

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

The description gives strong mode-selection guidance: use `topic` shortcuts for pre-mapped events or explicit ticker/slug pairs for custom comparisons. It also warns that pre-mapped topics often return compatibility warnings. However, it does not explain when to use this tool instead of related siblings such as polymarket_arbitrage or polymarket_edges.

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

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

Annotations already mark it read-only and idempotent. Description adds scoping details and the dual behavior (retrieve single vs list all). No contradictions.

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

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

Three efficient sentences, front-loaded with purpose, no filler. Every sentence adds value.

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

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

Covers retrieval purpose, listing, scoping, and pairing with related tools. Lacks only minor details like error handling on missing key, but acceptable for a simple read tool with annotations.

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

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

Schema already fully describes the single parameter (key), including the omit-to-list-all behavior. Description reinforces that but adds no new semantic details 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?

Describes retrieving a saved value or listing all keys, explicitly naming the companion tool 'remember' and distinguishing itself from siblings like 'forget'.

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

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

States when to use: to look up stored context without re-deriving, and scopes to identifier. Does not explicitly exclude alternatives, but pairing with remember/forget provides implicit 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 and destructiveHint=false. Description adds behavioral context: events contain source, citation_uri, raw payload; polling is safe; effect of mark_read on future calls. No contradictions.

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

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

Description is 4 sentences, front-loaded with main purpose, no filler. Every sentence adds unique information. 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, description specifies what each event carries (source, citation_uri, payload). Addresses polling, filtering, and alternative access. Complete for a read-only list tool with moderate parameter count.

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

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

Schema covers all 5 parameters (100%). Description adds context: explains mark_read's effect (flags events read, controls next call), provides filter example (sec_8k), and clarifies ISO timestamp usage. 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?

The description clearly states 'Pull fired events from your subscription feed' with specific verb and resource. It distinguishes from sibling tools like list_subscriptions by focusing on event retrieval rather than subscription management.

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

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

Provides explicit guidance on filtering (type, since), using mark_read for read tracking, and notes that polling works. Also mentions an alternative HTTP endpoint for scripts/dashboards. Lacks direct comparison to siblings, but no ambiguity exists.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details the tool's behavior: it fans out to SEC EDGAR, GDELT→GNews with fallback logic, and USPTO with a noted soft-fail regarding API sunset. It also mentions output structure including citations.

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, while a single paragraph, efficiently compresses a lot of information without waste. It is front-loaded with examples but could benefit from additional structuring (e.g., bullet points for sources). Still, it is concise for the complexity.

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

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

Given no output schema, the description covers all essential behavioral aspects: data sources, fallback, error handling (soft-fail), output grouping, citation URIs, and alternative tool usage. It is comprehensive for a tool with three parameters.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds extra context by providing concrete examples for 'since' (ISO date and relative shorthand) and 'value' (ticker or CIK), enhancing understanding beyond the schema alone.

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

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

The description opens with example queries and clearly states it provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call,' specifying verb, resource, and scope. It also distinguishes from the sibling tool 'entity_profile' by noting when to use the alternative.

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

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

The description explicitly advises when to use this tool (for 'what's new' queries) and when to use 'entity_profile' instead (static profile). It also offers practical guidance on the 'since' parameter with examples like '30d' or '1m'.

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 writable, non-destructive, and idempotent. Description adds key behavioral details: persistence duration (24 hours for anonymous, persistent for authenticated) and scoping by identifier. Minor lack of size limits but overall strong.

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

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

Four sentences, all essential. First sentence clearly states purpose. Subsequent sentences add usage, pairing, and behavioral details. No redundancy.

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

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

Given the simple key-value pair and 100% schema coverage, description fully specifies when and how to use, including persistence details. No missing information for effective agent invocation.

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

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

Schema covers both parameters with descriptions. Description adds examples and clarifies the nature of values (e.g., findings, addresses). Adds meaningful context 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 saves data for later reuse, using specific verbs 'Save data' and 'reuse later'. It distinguishes from siblings like 'recall' and 'forget' by mentioning them and their purposes.

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

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

Provides explicit when-to-use guidance with examples (resolved ticker, target address, etc.) and differentiates behavior based on authentication status. Implies when not to use by focusing on persistence.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral context: graceful degradation of LEI/FIGI enrichment, explicit labeling of unresolved identifiers, source attribution for each identifier, and internal cascading through multiple endpoints. This is all consistent with 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 dense and front-loaded with example queries and a clear purpose statement. It is a single long paragraph, but the structure using 'SUPPORTED TYPES' and semicolon-separated details helps digestibility. Some extra detail (e.g., the pipeworx citation URI) is slightly verbose but still informative.

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

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

With no output schema, the description carries the full burden of explaining return behavior. It thoroughly covers returned identifiers, their sources, unresolved identifier handling, non-US issuer coverage, and degradation behavior. This makes the tool's behavior fully predictable for an agent.

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

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

While the schema covers 100% of parameters, the description adds rich meaning beyond the raw definitions. It explains the 'company' and 'drug' types in detail, clarifies accepted input formats for 'value' (ticker, CIK, ISIN, name), and gives concrete examples such as 'AAPL' and '0000320193.' This goes far beyond the schema's terse descriptions.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides concrete example queries and distinguishes itself from siblings by emphasizing it produces IDs needed by other tools, not a profile or comparison.

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

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

Excellent guidance is given with 'Use FIRST whenever you have a name but need an ID.' It also explains the two supported entity types and their specific resolution behaviors. However, it does not explicitly state when not to use the tool or name alternative tools, so it stops short of a 5.

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

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

Annotations indicate readOnly, openWorld, and idempotent. The description adds that the tool probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density, which goes beyond annotations. No contradictions.

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

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

The description is two sentences, front-loaded with the core purpose, and provides concrete details without extraneous information. 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?

With 4 parameters, 1 required, and no output schema, the description adequately explains the tool's behavior and output format (ranked list). It covers necessary context for an agent to use it correctly.

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

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

Schema description coverage is 100%, but the description adds meaning beyond the schema, such as treating the first entity as the 'subject' and explaining the context parameter. This adds value for the agent.

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

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

The description clearly states the action 'Compare AI visibility across multiple entities side-by-side', specifies the resource (entities), and differentiates from sibling tools like ai_visibility_check by noting it ranks results and is useful for competitive audits.

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

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

The description explicitly frames the tool for competitive AI-marketing audits with an example question, providing clear context. It does not explicitly state when not to use or list alternatives, but the usage scenario is well-defined.

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 significant behavioral context: it fans out across two services, handles partial failures gracefully, explains that bundlephobia's first measurement can take 5-30 seconds, and lists possible failure sources (sources_failed).

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

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

The description is front-loaded with the core purpose and packed with necessary details. While relatively long, every sentence adds value (scope, behavior, output, limitations). Could be slightly condensed but still efficient.

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

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

Given the tool's complexity (multiple external services, async behavior, partial failures) and the absence of an output schema, the description fully documents the return structure (summary block, per-advisory detail, links, recent alternatives), failure modes, and ecosystem constraints. No gaps remain.

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

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

Schema coverage is 100% with both parameters described. The description adds minimal extra meaning beyond the schema (e.g., acknowledging scoped packages, version defaults to latest). Baseline of 3 is appropriate as the description does not significantly enhance parameter understanding.

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

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

The description clearly defines the tool as a composite check for npm packages, specifying the exact resources (deps.dev and bundlephobia) and contrasting with sibling tools by stating the ecosystem scope (NPM only) and mentioning alternatives for other ecosystems.

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 ('is X safe / popular / small') and guidance on alternatives for non-NPM ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'). Does not explicitly state when not to use, but the ecosystem limitation is clear.

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

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

Annotations already declare safety and idempotence; the description adds concrete implementation details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. 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?

Two tightly packed sentences: first states purpose and usage, second adds technical detail. Every sentence serves a clear function with no redundancy.

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

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

Despite lacking an output schema, the description fully explains return values (passages with offsets and scores), covers limitations (truncation flag), and ties to sibling tool workflow. Complete for a simple retrieval 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 the query parameter with natural-language examples (e.g., 'supply-chain risk'), specifying the default for limit, and clarifying the text parameter's max size. This incremental context justifies a 4.

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

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

The description clearly states that the tool performs semantic search inside a fetched record, using verbs like 'search inside' and 'get back'. It specifically mentions SEC filings, articles, and tool results, and distinguishes itself from sibling tools like ask_pipeworx_grounded.

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 explicitly advises using this tool when the record is too large for the prompt, and suggests pairing with ask_pipeworx_grounded for grounding over passages. It also notes that passages carry offsets for verification.

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 authentication requirement, SMS rate limit (10/day), webhook secret one-time return, and auto-disable after 10 failures. Adds value beyond annotations which only indicate idempotency and non-destructive nature.

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 dense paragraph, front-loaded with purpose and requirements. Could benefit from bullet points for types and delivery, but remains concise and readable.

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 authentication, subscription types, delivery channels, constraints, and response content. Missing explicit return value description, but schema doesn't define output. Sufficient for the tool's complexity.

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

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

Provides type-specific parameter details (e.g., sec_8k items, polymarket topic, delivery channel constraints) that go beyond the schema descriptions. With 100% schema coverage, the description enriches understanding significantly.

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 creates a proactive monitoring subscription and returns the new subscription ID. It distinguishes from sibling tools like unsubscribe and list_subscriptions.

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

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

Describes when to use (live-data event streaming), prerequisites (Pipeworx OAuth account), and supported types/delivery channels. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral context by detailing that it returns categorized example questions and that calling without arguments gives a full spread, while passing topic focuses results. This exceeds annotation coverage, though the exact response structure is not specified.

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 front-loaded with common queries, but it contains no unnecessary words. It could benefit from bullet points for categories, but overall it is efficient and informative without being 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?

Given the absence of an output schema, the description fully explains what the tool returns (categorized example questions) and its role as an onboarding entry point. It covers usage, focus options, and learning meta-tools, making it complete for its intended purpose.

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

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

Schema coverage is 100%, but the description adds significant semantic value by listing the allowed topic values and explaining the effect of omitting the parameter (full spread). This goes beyond the schema description, which only says 'Optional focus area'.

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 the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It uses specific verbs like 'suggest questions' and identifies the resource as Pipeworx capabilities, distinguishing it from sibling tools like ask_pipeworx or entity_profile.

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

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

The description explicitly advises using this tool first when unsure about Pipeworx's capabilities, and explains how to focus via optional topic parameter. It also states the purpose of learning meta-tools, providing clear context for when to use it.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds that the row is deactivated (not deleted) and historical events remain available via recent_alerts. This provides useful behavioral context not covered by annotations.

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

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

Two sentences with no redundant information. The most critical information (action, ownership, effect) is front-loaded. Every sentence adds value.

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

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

Given the tool's simplicity (1 required parameter, no output schema), the description fully covers the purpose, usage constraints, and behavioral impact. 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 that the 'id' parameter is a subscription uuid returned by subscribe, which provides meaningful context beyond the schema's description.

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

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

The description clearly states the action ('Cancel a subscription by id') and the resource ('subscription'). It distinguishes from sibling tools like 'subscribe' (create) and 'list_subscriptions' (list) by specifying that it cancels a specific subscription by its ID.

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 indicates when to use the tool ('Ownership is enforced — you can only cancel your own subscriptions'), providing important context. However, it does not explicitly state when not to use it or mention alternatives, though the sibling tools provide implicit contrast.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds crucial behavioral context: the meaning of could_not_verify (check did not happen, not evidence), unsupported (no source coverage), the verification_error payload, and the guaranteed citation/reasoning. This goes well beyond what annotations provide.

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

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

The description is dense but front-loaded with trigger phrases and a clear main definition. Every sentence contributes behavioral or usage value; the only minor inefficiency is the slight overlap between the 'Replaces 4–6 sequential calls' phrase and the routing details.

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?

Because there is no output schema, the description correctly takes responsibility for explaining return values: the verdict enum, actual value with pipeworx:// citation, reasoning, and the verification_error attribute. It also covers both execution modes and edge-case semantics, making it self-sufficient.

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

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

Schema coverage is 100% for both parameters with examples. The description adds meaningful semantics beyond schema by explaining that tolerance_pct overrides the claim-wording threshold, caps at 5%, and recommending 1–2% for hallucination detection. This enriches the schema-only 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 states a specific verb ('verify') and resource ('natural-language claim') along with concrete trigger phrases. It clearly distinguishes the company-financial structured path from the grounded fallback for any other factual claim, separating it from generic research or Q&A tools.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides clear routing rules for financial vs. non-financial claims. However, it does not name sibling tools as alternatives or state what should not use this tool for, so it lacks explicit exclusions.

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