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 establish read-only, idempotent, open-world behavior. The description adds useful behavioral context by disclosing that the tool acts as a router, fills arguments automatically, and returns structured answers with stable citation URIs. This goes beyond the annotations without contradicting them, though it does not mention failure modes, latency, 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 front-loaded with the most important directive and provides valuable domain lists and trigger phrases. However, it is verbose and contains redundant phrasing, notably repeating 'even if web search could also answer it' and ending with an incomplete 'Examples: ...' tail. It earns each section less cleanly than a tighter definition would.

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 orchestrator tool with no output schema, the description adequately covers what the tool does, when to use it, what domains it handles, and what kind of return value to expect. It is complete enough for selection and invocation, though edge cases and sibling-tool routing boundaries are not addressed.

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

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

The input schema covers all parameters at 100% and already explains that question is a natural-language request with aliases q, text, input, query, and prompt. The description provides example queries but does not add substantive semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states that the tool takes a natural-language question, routes it to one of 5,798 tools across 1,517 verified sources, and returns a structured answer with pipeworx:// citation URIs. This is a specific verb+resource definition and it differentiates from web search. However, it does not explicitly differentiate from sibling variants like ask_pipeworx_beta or ask_pipeworx_grounded, so it stops short of a 5.

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 this over web search for factual, current, or historical data, and use it whenever the user asks 'what is', 'look up', 'find', 'get the latest', or similar. It also says 'START HERE for most questions.' It does not, however, state when not to use the tool or when to choose a sibling alternative, so it has clear context but no exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context beyond those annotations: that this is an experimental/live edge, that results are compared against the stable router to decide merges, and that it currently behaves identically to ask_pipeworx. This is a useful and honest description of potential variability in routing behavior.

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

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

The description is thorough yet compact. It front-loads the core identity (beta of ask_pipeworx), explains the experimental status, states the current no-candidate state, provides usage guidance, and addresses fallback concerns—all in a tight paragraph. No sentence is redundant; every sentence adds useful information.

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

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

This is a higher-complexity tool because its behavior depends on an experimental routing state. The description covers the current state, the comparison purpose, the fallback behavior, and the relationship to the stable sibling. Given the output schema is absent but the response shape is explicitly stated to match ask_pipeworx, the description is complete enough for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds the meta-semantics that all arguments are identical to the ask_pipeworx tool and that the question/request is routed to the same universal router. Because the schema fully covers the alias parameters, the extra value from the description is context rather than semantics.

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 purpose: it is a beta variant of ask_pipeworx with identical routing, arguments, and response shape, but with experimental routing improvements potentially enabled. This clearly distinguishes it from the stable ask_pipeworx sibling and explains its current live behavior. It is very explicit about what the tool is and what it is 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?

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and explains the comparison purpose against the stable router. It also clarifies that no candidate is active, so current behavior matches the stable version. This gives an agent clear guidance on when to select this tool versus ask_pipeworx.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial value by disclosing the exact return contract, refusal reasons, grounding constraint, and the extra LLM call cost. No contradiction exists between description and 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 but every sentence earns its place: it covers mode, mechanism, return shape, refusal behavior, use cases, and cost tradeoff. It is front-loaded with the core purpose before moving to details, and no content is redundant with schema or 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?

Given there is no output schema, the description fully compensates by specifying the success return fields, the refusal enum, and the refusal_reason values. It also includes cost and usage tradeoff information, making the tool safe and self-sufficient 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 description coverage is 100%, with the question parameter fully documented including aliases. The description adds no param-level detail, but this is unnecessary because the schema already handles parameter semantics clearly. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode' that extracts answers only from fetched tool results. It distinguishes itself from ask_pipeworx by emphasizing grounded extraction and explicit refusals, making the purpose unambiguous.

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

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

The description explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'). It also references ask_pipeworx as the alternative, providing clear routing 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 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?

Beyond the readOnly/openWorld/idempotent annotations, it reveals account and paid-plan requirements, parallel internal routing, gap[] and contradictions[] behavior, citation resolvability, semantic excerpting, and expected latency. No contradiction 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 long but information-dense, and key caveats like account requirements and the ask_pipeworx alternative are front-loaded. Minor redundancy around single-lookup routing and depth-mode explanation keeps it from being maximally crisp.

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

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

Even without an output schema, it details the findings packet fields, gaps[] behavior, contradiction scanning, citation availability, latency, auth, and usage boundaries. For a complex parallel research tool, this gives an agent enough context to select and invoke 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?

The schema already describes both parameters completely, so the baseline is 3. The description adds valuable extras: depth:thorough requires a paid plan, depth modes have different hop/gap-recovery behavior, and broad/multi-part questions are expected.

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 clear verb and resource: grounded multi-source research over 1,517 structured data sources in one call, returning a findings packet. It explicitly distinguishes itself from open-web search and from ask_pipeworx for single lookups, and gives concrete example questions.

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

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

It explicitly says when to use this tool: broad/multi-part questions over structured data. It also says when not to: single lookups should use ask_pipeworx instead, and unsigned-in users should use ask_pipeworx because it works on every tier.

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

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

Annotations already 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 signal read-only, open-world, and idempotent behavior, and the description adds substantial context beyond that: it fans out across SEC EDGAR, XBRL, USPTO, USAspending, FDA Purple Book, DOL LCA, news, and GLEIF, notes the USPTO PatentsView API sunset soft-fail, and clarifies sources_used/sources_failed semantics. This is exactly the kind of behavioral context annotations cannot convey.

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

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

The description is dense and front-loaded, but it is one long unbulleted paragraph with six redundant opening query examples and an explicit restatement of parameter semantics already present in the schema. Every sentence carries some information, but the structure could be tighter and easier for an agent to parse with bullets or by trimming repeated examples.

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

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

With no output schema present, the description fully compensates by enumerating every returned section, the source-failure behavior, supported input forms, and the expected response for private companies. An agent has enough detail to invoke the tool correctly and interpret both success and no-data outcomes.

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

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

Schema coverage is 100%, and the schema already documents that type accepts 'company' or 'ticker' interchangeably and that value can be a ticker, zero-padded CIK, or company name resolved via SEC EDGAR. The description repeats this information and adds illustrative examples, but it does not materially extend the parameter semantics beyond what the input schema already provides.

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

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

States its function precisely: a full cross-source profile of a US public company in one parallel call, with explicit examples of triggering queries. It differentiates itself from chaining single-pack SEC/XBRL/news lookups, though it does not name sibling tools like compare_entities or deep_research, so it stops just short of full sibling differentiation.

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

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

Gives an explicit preference rule: ALWAYS PREFER this over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view. It also tells the agent how to interpret edge cases: private companies return resolved:false with a notes line, and empty sections mean no data, not a bug.

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?

Even though annotations already mark this as read-only, idempotent, and non-destructive, the description adds crucial behavioral caveats: spreads are gross not net, pairings are unverified, compatibility warnings are expected, and most pre-mapped topics currently return warnings. It also clarifies that temporal_alignment null means 'could not be computed', not 'aligned'.

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 the content is dense and well-structured with clear labels like TWO MODES, RESPONSE, SAFETY FIELDS, and Codes. It is front-loaded with the core purpose, and every sentence carries substantive caveats or operational details, though it could be somewhat tightened.

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

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

With no output schema, the description carries the full burden of explaining return values, safety fields, compatibility codes, per-entry flags, skipped-comparison counters, fee treatment, and temporal alignment semantics. It is exceptionally complete for a complex tool and leaves no critical operational ambiguity.

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

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

Schema coverage is 100%, so the baseline is already solid. The description adds meaningful semantics by explaining that `topic` auto-fetches the matching event on each venue, explicit params override the topic-mapped side, and custom pairings use the same token-overlap matcher. It also warns that pre-mapped topics are not guaranteed tradeable.

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 first sentence states exactly what the tool does: it reports the cross-venue spread between Kalshi and Polymarket for the same resolving question. The two explicit modes and the 'same outcome on both sides' condition make the purpose precise and clearly distinguish it from intra-venue 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?

The description gives clear guidance on when to use `topic` shortcuts vs explicit ticker/slug pairings, and says both modes run the identical matcher. It does not explicitly compare this tool against sibling alternatives like polymarket_arbitrage, but the mode-selection guidance is strong 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 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 mark read-only, open-world, idempotent, non-destructive. The description adds valuable behavioral context: graceful degradation if GLEIF/OpenFIGI is unavailable, explicit `unresolved` reporting instead of omission, and no-assertion behavior on ambiguous names. This goes well beyond the annotations.

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

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

The description is extremely dense, with long parenthetical asides and multiple clauses per sentence, making it harder to scan. It is front-loaded with purpose, but the company-type block in particular reads as a wall of text; some redundancy (e.g., 'which is the correct answer to an issuer name that does not identify a single bond') could be trimmed. Still, most sentences carry useful information.

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

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

The tool has no output schema, so the description carries the burden of explaining the result shape. It does so by enumerating CIK/ticker/LEI/FIGI/RxCUI, the `figi_candidates` ambiguity case, the `unresolved` field, and source labeling — sufficient for an agent to know what it will receive. It also covers input variants and failure/degradation behavior, making it complete for an agent to call and interpret.

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 100%, but the description significantly enriches the `value` parameter with concrete examples ('NEW YORK ST DORM AUTH'), an anti-example about trailing security-class words, and accepted formats (ticker, CIK, ISIN, name). It also clarifies `type` semantics by describing exactly what identifiers each entity type resolves to, so the agent knows how to populate both params.

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

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

The description opens with concrete example queries and a specific verb-resource pair: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly positions the tool as the name-to-ID gateway, distinct from sibling tools like entity_profile or compare_entities, and reinforces with 'Use FIRST whenever you have a name but need an 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?

It provides explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also gives conditional guidance for the two types (company/drug) and for ambiguous matches ('asserts nothing and returns figi_candidates'). However, it does not explicitly name alternative tools that should be used instead in specific situations, so the exclusion guidance is implicit rather than explicit.

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.