Itis

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that it probes LLMs, returns per-model data, and that passing _apiKey probes Anthropic with direct payment. No contradictions.

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

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

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

All parameters are covered in schema with descriptions, annotations cover safety, and the description explains the return structure despite no output schema. Complete 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?

Schema coverage is 100%, baseline 3. The description adds context: entity is what to ask about, models list with defaults, _apiKey for Anthropic, context for disambiguation. This enhances understanding.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It specifies the default model and optional Anthropic probing, distinguishing it from sibling tools like deep_research or compare_entities.

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

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

The description mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It does not explicitly state when not to use or compare to siblings, but the context is clear.

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

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

Annotations already declare this as read-only, non-destructive, and idempotent, so the bar for additional disclosure is lower. The description adds meaningful behavioral context: it routes to one of 5,706 tools across 1,493 sources, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, and works on every tier with one fast call. It also explains that it can handle breaking news through routing to live news feeds.

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

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

The description is longer than average, but it is front-loaded with the most important instruction and every sentence carries functional value: scope, alternatives, examples, and tier behavior. Some redundancy exists ("PREFER OVER WEB SEARCH" is restated as "even if web search could also answer it"), but the structure makes the key routing decision immediately clear.

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

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

For a broad routing tool with no output schema, the description covers the essential contextual needs: what it does, when to use it, how it chooses sources, what the output looks like, and which sibling tools to use for different scenarios. The alias information is in the schema, while the description provides the decision framework an agent needs to invoke this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents the parameter and its aliases. The description goes beyond the schema by clarifying the kind of natural-language questions the parameter should contain, listing domains, trigger phrases, and concrete examples. This helps an agent formulate a valid question even though the schema already names the parameter.

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

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

The description opens with a specific directive: "PREFER OVER WEB SEARCH for questions about current or historical data," and then names concrete domains like SEC filings, FDA data, economic statistics, patents, and news. It clearly distinguishes the tool from siblings by positioning it as the default entry point and explicitly contrasting it with ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance, including trigger phrases like "what is," "look up," "find," and "get the latest," and explains when to step up to alternatives: "for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research." This leaves little ambiguity about tool selection.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds substantial context beyond that: candidate routing improvements are enabled live only during tests, the last candidate was retired on outcome evidence, and the tool falls back to nothing because it is itself a full working router. This gives the agent accurate expectations about variability and reliability.

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 compact and front-loads the key identity as a beta router. Each sentence contributes useful information, though there is minor redundancy between 'identical universal router' and 'currently matches ask_pipeworx exactly.'

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 one-required-parameter tool with no output schema, the description covers what matters: identity, current candidate status, relationship to the stable router, usage guidance, and how to interpret its behavior. An agent has enough context to invoke it correctly and know what to expect.

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

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

The input schema fully documents the required 'question' parameter and all five aliases, so description-level parameter help isn't necessary. The description only says 'same arguments' without adding detail, which is acceptable given 100% schema coverage.

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 defines the tool as a beta version of ask_pipeworx: an identical universal router over 5,706 tools with the same arguments and response shape. It clearly differentiates it from the stable ask_pipeworx sibling by calling out the experimental edge, so an agent knows exactly what resource this is.

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

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

It explicitly says to use it exactly like ask_pipeworx when the newest routing is desired, and contrasts it with the stable router whose results are used for comparison. It also clarifies current state (no candidate active, so behavior matches stable), which is strong practical guidance for selection.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses key behaviors: it extracts answers using only the tool result, returns evidence verbatim, and provides explicit refusal reasons including not_in_source, no_tool_match, tool_error, data_truncated, and llm_error. It also transparently notes the extra LLM call cost. No contradiction with annotations.

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

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

The description is information-dense but every sentence earns its place. It front-loads the core value proposition, then covers routing, return shape, refusal semantics, use cases, and cost trade-off in a clear, structured manner without fluff.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete: it specifies success return fields, all refusal reasons, when to use, when not to use, and the cost relative to ask_pipeworx. An agent has enough context to invoke this tool correctly and interpret its result.

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 already describes all six parameters with 100% coverage, so the baseline is 3. The description does not add parameter-level meaning beyond what the schema provides, though it does clarify the overall intent of using natural language questions.

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, differentiated purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly states what the tool does (routes, fetches, extracts grounded answers) and distinguishes itself from ask_pipeworx by emphasizing grounded extraction and explicit refusal behavior.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative and cost trade-off: 'prefer ask_pipeworx for casual lookups' and 'costs one extra LLM call vs 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?

The description provides extensive behavioral detail beyond annotations: fan-out patterns, resolver contract, parent event extraction, news fallback behavior, safety short-circuits, spread liquidity warnings, and cancellation rule risk. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are all consistent and supplemented.

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 densely packed with essential information. It is front-loaded with the core purpose and uses examples. While it could be trimmed, every sentence adds necessary context for such a complex tool.

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

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

The description covers all aspects: input formats, fan-out examples, response shapes, resolver confidence, parent event extraction, news fallback, safety mechanisms, illiquid spreads, and cancellation rule risk. No gaps are apparent.

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

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

Schema coverage is 100%, but the description adds significant value: examples for the 'market' parameter, usage guidance for 'depth' (quick vs thorough), and 'include_raw' (default false, when to use true). It explains parameter behavior 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 and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data'. It clearly distinguishes inputs (slug, URL, question) and outputs (evidence packet, market-vs-model comparison). The purpose is explicit and non-tautological.

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

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

The description provides explicit usage guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also covers when to avoid (low-confidence matches, closed markets) and safety checks, making it clear when the tool is 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 indicate read-only, non-destructive, idempotent behavior. The description adds value by explaining that results are sorted by primary metric ('largest' reads off top), that off-calendar fiscal years are handled correctly, and that pipeworx:// citation URIs are returned. It could further clarify data freshness or potential latency.

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 information-dense but well-organized, starting with trigger phrases and then detailing behavior per type. It avoids unnecessary fluff, though some example queries could be trimmed without loss of clarity. The structure is front-loaded with the key use-case cues.

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 adequately explains what is returned (paired data, sorted results, citation URIs) and covers both entity types. It provides sufficient context for an agent to understand the tool's capabilities without external documentation.

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 both 'type' and 'values'. The description enriches these by providing concrete examples (tickers/CIKs for company, drug names for drug), specifying the 2-5 range, and explaining how each type affects the data pulled. This adds significant meaning beyond the schema.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs, provides trigger phrases, and distinguishes from sequential lookups. It specifies the data pulled for each type (SEC filings for companies, FAERS/FDA/trials for drugs), 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 advises preferring this tool over sequential single-pack lookups and gives example queries ('X vs Y', 'rank these companies'). It explains when to use type='company' vs type='drug' based on entity type. However, it does not mention cases where the tool should not be used (e.g., needing more than 5 entities or data beyond what is provided).

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/open-world/idempotent, and the description still adds materially: auth/paid-tier requirements, gap[] and contradictions[] behavior, hop and citation_uri semantics, semantic excerpting, and latency ranges. 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?

Long, but every block carries decision-relevant information: auth, routing, depth semantics, citation guarantees, latency. Front-loaded with the account requirement and the alternative tool, though a bit dense for parsing; bullets/headings would improve scannability.

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

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

Despite no output schema, the description specifies the findings packet structure, citation resolvability, gaps for unanswered facets, return durations, and when to prefer siblings. An agent has everything needed to decide, invoke, and interpret results.

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

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

Schema coverage is 100%, but the description goes beyond it by explaining what depth values actually change (quick no hop, standard gap-recovery, thorough lead-chasing and contradictions) and by clarifying that question can be broad because decomposition is the point.

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 names a precise verb and resource: grounded multi-source research across Pipeworx's structured data sources, decomposing a question into facets and routing to tools in parallel. It explicitly contrasts with open-web search and with ask_pipeworx, distinguishing it from the main sibling.

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

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

It gives explicit when-to-use guidance: best for broad/multi-part structured-data questions, and names alternatives for single lookups (ask_pipeworx) and breaking/current news. It also states a prerequisite (account required) and which tier each depth needs.

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 readOnly and idempotent. Description adds useful context: returns schemas with curated examples ready for direct invocation, no second lookup needed. No contradictions.

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

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

Well-structured: front-loads purpose, lists domains compactly, explains output format in one sentence, and ends with actionable usage tip. Every sentence adds value.

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

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

Despite no output schema, description fully explains return values (names, descriptions, schemas, examples) and how to use them. Sufficient for agent decision-making given tool complexity and 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 coverage is 100% with thorough descriptions. Description mentions aliases (already in schema) and provides examples, but does not add significant new parameter-level meaning beyond what the schema gives. Baseline 3 is appropriate.

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

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

Description clearly states the tool discovers tools by describing data/task, lists many domain examples (SEC, FDA, etc.), and specifies returns top-N relevant tools with schemas ready to call. It distinguishes itself from sibling tools like ask_pipeworx or deep_research which are specific-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 advises 'Call this FIRST when you have many tools available and want to see the option set'. Does not include when-not-to-use cases, but the context implies alternative when target tool is already known.

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 readOnly, idempotent, openWorld hints. Description adds details: fans across multiple sources, returns specific fields, patent sunset soft-fail, GDELT→GNews fallback. No mention of error handling or rate limits, but still strong additional context.

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

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

A single dense paragraph that is front-loaded with example invocations. Every sentence adds value, but the lack of structure (e.g., bullet points) makes it slightly harder to parse. Still efficient for the information conveyed.

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

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

Given two params and no output schema, the description covers return fields, data sources, limitations (patent sunset), and sorting. Lacks details on error handling for invalid inputs or source failures, but is largely complete for an agent to use effectively.

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

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

Schema coverage is 100% with each parameter described. Description reinforces that names are not supported and directs to resolve_entity, adding meaningful guidance beyond schema. Also notes zero-padded CIK format.

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

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

The description states 'full cross-source profile of a US public company in ONE parallel call' with specific verb 'profile' and resource 'company'. It clearly distinguishes from siblings like compare_entities and resolve_entity by emphasizing holistic one-call approach.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and notes to use resolve_entity if only a name is available. This provides clear when-to-use and when-not-to-use guidance.

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

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

Description confirms destructive nature (matches destructiveHint=true) and adds context about clearing sensitive data. Annotations already cover destructive hint; description adds moderate extra context but no detail on side effects or errors.

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

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

Two sentences plus a pairing note, front-loaded with action and resource. No wasted words, highly efficient.

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

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

For a simple single-parameter deletion tool with no output schema, description covers use cases and pairing. Lacks details on post-deletion behavior or error handling but 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% with parameter 'key' described as 'Memory key to delete.' Description adds no additional meaning beyond what schema provides, baseline 3.

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

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

Description clearly states 'Delete a previously stored memory by key,' specifying verb, resource, and scope. Distinguishes from siblings 'remember' and 'recall' by naming them explicitly.

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

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

Explicitly says when to use (stale context, task done, clear sensitive data) and pairs with remember and recall. No explicit when-not or alternatives, but clear context provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details: it fetches the page, extracts title/description/key links, emits standard llms.txt format, and outputs a single text blob. No contradictions with annotations.

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

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

The description is a single focused paragraph with no fluff. It front-loads the main purpose, then explains the process, and ends with use cases. 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?

For a simple generation tool with only 2 parameters and no output schema, the description covers the essential flow (fetch, extract, emit). It explains the output format and deployment location. The lack of output schema is compensated by the clear description of what is produced.

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

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

Schema coverage is 100%, so the description adds little beyond what the schema provides. The mention of default (25) and max (50) for max_links is implicit but not explicitly stated. Baseline 3 is appropriate since the schema already documents parameters well.

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

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

The description uses a specific verb ('Generate'), resource ('llms.txt file'), and target ('any URL'), clearly distinguishing it from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence'. It states the exact output and intended audience.

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 three use cases (client indexing, personal project drafting, competitor auditing), which guides when to use the tool. However, it does not state when not to use it or mention alternatives among the siblings.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, which cover safety and behavior. The description adds that it returns names 'in all languages' and gives examples. This adds mild context but does not contradict annotations. The description's contribution is adequate given the rich annotations.

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

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

The description is two sentences: the first states the core functionality and includes concrete examples; the second provides usage guidance and a keyless note. Every sentence is informative and front-loaded, with zero wasted words.

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

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

For a simple lookup tool with one parameter, no output schema, and no nested objects, the description is complete. It explains the tool's purpose, input source (TSN from search_taxa), and scope (all languages). No additional details are needed for correct usage.

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

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

The single parameter 'tsn' is fully described in the input schema with type, description, and examples. The description reiterates 'Taxonomic Serial Number, e.g. 180582', adding no new semantics beyond what the schema provides. With 100% schema coverage, baseline 3 is appropriate.

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

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

The description clearly states the verb 'Get', the resource 'vernacular (common) names', and the input 'TSN'. It provides concrete examples like 'Bobcat' and 'lynx roux', and distinguishes from sibling tools like search_taxa and get_hierarchy by focusing specifically on common names.

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

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

The description explicitly tells users to 'Pass a TSN from search_taxa', establishing a clear prerequisite and usage context. The note 'Keyless' implies no authentication is needed. However, it does not explicitly state when not to use this tool or mention alternatives, but the direct link to search_taxa is sufficient 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 the tool is read-only, non-destructive, and idempotent. The description adds that it returns each rank with tsn, name, rank, and parent_tsn, and mentions it is keyless. This transparently describes the output and access requirements.

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

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

The description is concise: three sentences covering purpose, return data, and prerequisites/cost. Every sentence adds value without unnecessary detail.

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 parameter, no output schema), the description covers the main aspects: purpose, output structure, and usage context. Lacks error handling details, but overall sufficiently complete.

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

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

The schema has 100% coverage for the single parameter tsn, describing it as 'Taxonomic Serial Number, e.g. 180582.' The description adds value by stating the TSN should come from search_taxa, providing additional context beyond the schema.

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

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

The description clearly states the tool walks the full taxonomic hierarchy from kingdom down to the taxon and its children for a given TSN. This distinguishes it from sibling tools like search_taxa and get_common_names, which serve different 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?

The description specifies that the TSN should come from search_taxa and that the tool is keyless (free). While it doesn't explicitly state when not to use it, the context of sibling tools and the explicit prerequisite provide good usage 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 readOnly, idempotent, non-destructive. The description adds that it returns specific fields and that the default is active subscriptions. No contradictions.

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

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

Two concise sentences: purpose, return fields, and usage guidance. No redundant information.

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

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

For a simple list tool with one optional parameter and rich annotations, the description is sufficient. No output schema needed.

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

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

Schema coverage is 100%. The description does not add meaning beyond the schema's parameter description. The mention of 'active' aligns with the default, but no new depth.

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 lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). This distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

The description advises using this before adding more subscriptions or to find an id to cancel. This provides clear context, though it does not explicitly mention when not 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?

Annotations are all false, offering no safety or behavior hints, so the description carries the burden. It discloses the claim_token workflow, daily rate limit (5 per identifier per day), that feedback is free and doesn't count against quota, and that the team reads digests daily. These are material behavioral details an agent needs before calling.

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: every sentence contributes (when, when-not, token flow, limits, cost). It is front-loaded with the core purpose and structured logically, though slightly longer than necessary for a simple feedback 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 no output schema and simple return value (a claim_token on filing), the description fully covers what an agent needs: how to file, how to check status, rate-limits, and scope. It even mentions that filing without an account still returns a claim_token, covering the edge case.

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

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

Schema already covers all 4 parameters with 100% description coverage, so baseline is 3. The description adds practical context: claim_token is for reading a previous report and should be passed alone, message should be specific with 1-2 sentences typical, and type examples tie to the reported scenarios. This extra guidance nudges the score to 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 opens with a specific verb+resource ('Tell the Pipeworx team something is broken, missing, or needs to exist'), enumerates the message types (bug, feature/data_gap, praise), and explicitly scopes to 'tools served by this Pipeworx connection,' distinguishing it from sibling research tools like ask_pipeworx and entity_profile. This leaves no ambiguity about what the tool does.

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

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

Explicitly states when to use (bug, feature/data_gap, praise) and when not to ('if the tool came from a different MCP server... file it with that server instead'), plus instructions on how to describe the issue (in terms of Pipeworx tools/packs, don't paste the end-user's prompt). This goes far beyond typical tool descriptions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: data source (CF analytics-engine), no PII, and caching policy (5min-1h). This exceeds annotation coverage without contradiction.

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

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

The description is efficiently structured: main purpose in first sentence, then bullet-like use cases, then data provenance and caching. Every sentence adds unique value, no redundancy. Front-loaded with essential info.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description fully covers what the tool does, what it returns, use cases, and behavioral details. Annotations already handle safety, so completeness is high.

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 covers the single parameter (window) with enum and description. The description adds semantic guidance: shorter windows for hot trends, longer windows for steady-state demand. This provides extra interpretative value beyond the schema.

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

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

The description clearly states it returns trending data from other AI agents (top tools, packs, call volume) over specified time windows. It uses specific verbs like 'returns' and distinguishes from sibling tools by focusing on aggregate usage signals rather than individual queries or entity lookups.

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

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

The description lists three explicit use cases (discovering hot data sources, confirming canonical choice, aligning with agent needs). It does not explicitly mention when NOT to use or name alternative sibling tools, but the provided contexts are sufficiently clear for selection.

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

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

The description adds significant behavioral context beyond the annotations (which indicate read-only, idempotent, open-world). It explains the fill check against live CLOB depth, the semantic anchor (Jaccard similarity threshold), the partition filter (placeholder slugs), and the resulting trade signals. No contradiction with annotations.

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

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

The description is well-structured with clear sections and front-loaded purpose, but it is lengthy (multiple paragraphs) and contains some technical jargon that could be condensed. Every sentence is justified, but brevity could improve 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 the complexity of the tool and lack of output schema, the description is exceptionally complete. It explains monotonicity, partition checks, semantic anchor, fill checks, response format (opportunities array), and directs to associated tools for further use. No gaps identified.

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

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

With 100% schema description coverage, baseline is 3. The description goes far beyond, explaining the difference between event and topic modes, providing example values (e.g., 'fed-decision-may-2026'), noting that full Polymarket URLs are accepted for event, and describing the detailed behavior of each mode.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes itself from sibling tools by specifying the exact methodology and modes (trending_scan, event, topic), and references a sibling tool (polymarket_fill_risk) for custom sizing.

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

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

The description provides explicit guidance on when to use each mode: no args for trending_scan, 'event' for specific event slug, 'topic' for cross-event scanning. It also specifies when not to trade (realizable_edge_pp <= 0) and directs to polymarket_fill_risk for custom sizing. Examples of event slugs and topic questions are given.

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, not destructive. Description adds extensive behavioral context: model families, edge calculation, response structure with by_segment, diagnostics, caching at KV level, Fed bets exclusion. 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?

Fairly long (~300 words) but every sentence adds unique value. Front-loaded with purpose and segmentation. Could be slightly more terse, but dense information justifies length.

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

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

For a complex tool with 9 params and no output schema, the description covers input knobs, response structure (by_segment, fed_candidates, diagnostics), edge computation details, and caching. Agent has everything to understand inputs, outputs, and behavior.

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

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

Schema coverage is 100%, but description adds operational meaning beyond schema descriptions. For example, explains that slippage_pp is subtracted from raw edge before ranking, min_kelly suppresses small opportunities, and min_partition_leg_kelly applies to per-leg Kelly. Very helpful.

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 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', with a specific verb+resource and a use case sentence. Distinguishes from siblings by naming specific segments and hinting at unique capabilities.

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 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets'. Does not directly contrast with siblings like polymarket_arbitrage, but purpose is clear enough to decide when to use.

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

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

Annotations indicate safe, read-only, idempotent, non-destructive behavior. The description adds significant detail: explains response fields (tracked, expired, snapshot_dates), computation of trend and decay, data gaps, TTL limits, and that decay is based on daily closes. No contradictions.

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

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

The description is well-structured: starts with a high-level purpose, then details response fields and limitations. It is somewhat lengthy but every sentence provides useful information. Could be slightly more streamlined 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?

For a tool with 2 optional parameters and no output schema, the description is remarkably complete. It explains the response format thoroughly, covers edge cases (expired opportunities, data gaps), and notes limitations (TTL, snapshot start). The agent has enough information to use the tool correctly.

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

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

Schema covers both parameters with descriptions. The tool description adds default values (14 for days, '1wk' for window), clarifies the max for days (30), and explains the window parameter as snapshot family. 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 clearly states it provides edge persistence and decay telemetry from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges by focusing on historical tracking.

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

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

The description explains when to use this tool: to understand edge history and distinguish between new and old wide edges. It does not explicitly mention when not to use it or alternatives, but the context implies it is for historical analysis rather than current snapshots.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds that it walks the ladder, returns verdicts (clean|degraded|cannot_fill), clamps size, and names forced directional risk legs. 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?

Well-structured with bold headers and bullet-like phrasing. Slightly verbose in explaining return fields but front-loaded with critical usage guidance. Each sentence adds value.

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

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

No output schema, so description fully details return values: top_of_book, vwap_fill_price, slippage, shares_filled, verdict, and for basket: theoretical vs realizable sum, capture_ratio, profit, thin legs, max clean notional, forced directional risk. Complete for complexity.

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

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

Schema coverage 100% with descriptions. Description adds context: default side for basket is auto (based on partition sum), size_usd interpretation for basket (settlement notional), and clamp range 10-1,000,000. Adds value beyond schema.

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

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

Description clearly states 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explains single-market and basket modes, distinguishes from siblings like polymarket_arbitrage and polymarket_edges by naming them as consumers of this check.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Explains why: theoretical overround on thin books not capturable and partial fills cause directional risk.

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 substantial behavioral context: compatibility_codes[] semantics, non_equivalent_bet_shapes, temporal mismatches, unclassified legs never being paired, and skipped cross-type/cross-subtype counters. 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 front-loaded with the core purpose and then organized into labeled sections: TWO MODES, RESPONSE, SAFETY FIELDS, and compatibility codes. Every section earns its place given the tool's complexity, though some code enumeration could have been compressed.

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?

There is no output schema, so the description carries the full burden of explaining return values and behavior. It covers leg-by-leg prices, matched spread[], top_spreads_pp, compatibility fields, skipped/unclassified-leg handling, temporal_alignment, and warning flags—sufficient for an agent to invoke and interpret the tool correctly.

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

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

The schema already covers each parameter, so the baseline is 3, but the description adds genuine value by defining the two-mode interpretation, enumerating all 10 topic shortcuts, and explaining how explicit tickers/slugs override the mapped side. It does not repeat schema descriptions verbatim and meaningfully augments them.

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 opening sentence states a specific resource and action: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges, which address related but distinct concerns.

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 explains two modes—topic shortcuts vs explicit kalshi_event_ticker + polymarket_event_slug pairings—and gives practical caveats: most pre-mapped topics return compatibility_warning today and pre-mapped ≠ tradeable. It does not explicitly name alternative sibling tools for when not to use this one, but it provides strong within-tool 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 already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping to identifier (anonymous IP, BYO key hash, account ID) and the list-all behavior when key omitted. No contradictions.

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

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

Three sentences: first gives core function, second provides use cases, third explains scoping and pairing. No redundant text, front-loaded, every sentence serves a purpose.

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

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

Given simple one-param optional tool with rich annotations, description fully covers purpose, usage, scoping, and relationships. No missing elements for effective use.

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

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

Schema covers the single optional parameter with description 'Memory key to retrieve (omit to list all keys)'. Description reiterates that but adds no new semantic detail beyond what schema already provides. Baseline 3 for 100% coverage.

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

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

Clearly states it retrieves a value saved via remember or lists all keys. Distinguishes from siblings like remember and forget by explicitly pairing with them and stating opposite actions.

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 examples (look up stored context) and mentions pairing with remember/forget. Advises omitting key to list all, giving concrete usage pattern.

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 a safe, read-only, idempotent operation. The description adds significant behavioral context: it specifies that each alert carries source, citation_uri, and raw event payload, explains the effect of mark_read (flagging as read), and confirms polling is safe. No contradictions with annotations.

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

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

The description is a compact paragraph of 4-5 sentences. It front-loads the core purpose, then efficiently covers return values, filters, mark_read behavior, and polling advice. Every sentence adds value without redundancy.

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

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

Despite having no output schema, the description details key return fields (source, citation_uri, raw event payload). It explains the effects of optional parameters and confirms polling safety. For a tool with moderate complexity and no required parameters, this is fully adequate and leaves no important gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context beyond the schema, particularly for the mark_read parameter, by explaining its side effect of making subsequent calls return only newer events. This deeper explanation aids 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 first sentence clearly states the verb ('Pull') and resource ('fired events from your subscription feed'). It implies the tool retrieves recent alerts. However, among many sibling tools, there is no explicit differentiation from similar tools like 'recent_changes' or 'subscribe', which would help an agent choose this tool over others.

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

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

The description notes that polling is acceptable and provides an alternative REST endpoint for scripts/dashboards, giving useful context for when to use this tool vs. another access method. It does not explicitly state when not to use it or contrast with sibling tools, but the provided context is sufficient for an agent to decide.

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

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

Annotations already indicate safe, idempotent read behavior. The description adds significant behavioral context: parallel fan-out, GDELT→GNews fallback, USPTO soft-fail, relative date shorthand, and return structure. No contradictions.

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

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

The description is a single paragraph but packs essential information efficiently. Minor improvement could be structuring with bullet points, but 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 complexity (multiple sources, fallback, window handling) and no output schema, the description covers return structure, source grouping, and citation URIs, making it complete for 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 coverage is 100% with parameter descriptions. The description enhances by explaining `since` relative shorthand and `value` accepting ticker or CIK, adding value beyond schema.

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

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

The description clearly states the tool provides a change feed for a company over a time window, listing specific sources (SEC EDGAR, GDELT→GNews, USPTO) and distinguishes from sibling `entity_profile` which offers a static 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 includes explicit natural language query examples and directs users to `entity_profile` for static profile needs, providing clear when-to-use and when-not-to-use guidance.

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

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

Discloses scoping by identifier, 24-hour retention for anonymous sessions, and persistence for authenticated users. Annotations (idempotentHint=true, destructiveHint=false) are consistent. No contradiction.

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

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

Three sentences, each earning its place: purpose, usage condition, storage details. No fluff or repetition. Front-loaded with the key action verb 'Save'.

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 2-param tool with no output schema and rich annotations, the description covers all essential aspects: what, when, how stored, and lifecycle. No gaps.

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

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

Schema coverage is 100% with clear parameter descriptions (key naming convention, value as text). The description adds 'key-value pair' context but offers minimal additional semantics beyond the schema. Baseline score applies.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It includes specific examples (resolved ticker, target address, etc.) and distinguishes itself from sibling tools like recall and forget.

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

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

Explicit guidance on when to use ('when you discover something worth carrying forward') and pairing with recall/forget. Context signals show 2 siblings are directly related (recall, forget), making differentiation 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 destructiveHint=false, so the safety profile is known. The description adds valuable behavioral context: cascades through multiple endpoints, graceful degradation if GLEIF/OpenFIGI is unavailable, identifiers labelled with source, and unresolved identifiers explicitly stated. It doesn't mention rate limits or authentication, but annotations cover the key safety aspects.

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 appropriately structured: starts with user-facing examples, then supported types, then enrichment details and fallback behavior. Every sentence adds factually useful information (degradation, source labels, unresolved handling). It's dense but not wasteful, though it could be tightened slightly without losing meaning.

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

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

For a tool with two entity types, multiple ID systems, no output schema, and complex internal cascading, the description covers the key return fields (CIK, ticker, LEI, FIGI, RxCUI, etc.), behavior on resolution failure, and fallback logic. It's nearly complete, though it doesn't spell out the exact JSON response structure or error handling beyond 'unresolved'. Still quite thorough for the complexity.

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

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

Schema coverage is 100%, so parameters are documented. The description adds meaningful semantics beyond the schema: concrete value formats (ticker, CIK, ISIN, or name), explains ISIN resolves to the legal entity via GLEIF mapping, and gives drug examples (brand or generic name). This is more than the baseline 3 for a high-coverage schema.

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

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

The description uses a specific verb+resource construction: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly distinguishes from siblings by stating 'Use FIRST whenever you have a name but need an ID.' The examples of query phrasing and supported entity types make the purpose unmistakable.

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

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

Provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also implies when not to use (when you already have an identifier) and gives context by saying it replaces 2-3 manual lookups. However, it doesn't explicitly name alternative tools like entity_profile or get_hierarchy, so it stops just short of a full when-not-to-use comparison.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It also notes the optional API key requirement for anthropic model. 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 efficient sentences that front-load the core action ('Compare AI visibility across multiple entities side-by-side') and immediately follow with detail. Every sentence adds value with no redundancy.

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

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

Despite no output schema, the description clearly states the return format ('ranked list with score, confidence, signal density per entity'). Given the tool's moderate complexity (4 params, all described in schema) and the descriptive output summary, the description is complete for an agent to understand what the tool does and what it returns.

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

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

Schema description coverage is 100% so baseline is 3. The description adds extra semantics: entity[0] is treated as 'subject' for narrative, context disambiguates common names, and models array has default behavior. This elevates the score above baseline.

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

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

The description uses specific verbs ('Compare', 'Probes', 'ranks', 'surfaces') and clearly identifies the resource (AI visibility across multiple entities). It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic) by emphasizing competitive side-by-side comparison.

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

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

The description explicitly frames usage for competitive AI-marketing audits and gives a concrete example question. It implies when to use (side-by-side comparison) but does not explicitly state when not to use or list alternatives, though the context of 'your brand + N competitors' provides clear applicability.

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

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

Annotations declare readOnlyHint and idempotentHint. Description adds that partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, and sources_failed will list timeouts. This is useful beyond annotations.

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

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

Description is detailed but every sentence adds value: composite nature, sources, use cases, ecosystem info, partial failure handling. Slightly long but not wasteful. Could be more structured (e.g., bullet points) 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?

For a read-only composite tool with no output schema, the description thoroughly explains return fields (summary block, per-advisory, links, alternatives) and behavior (partial failures). Completely prepares the agent for invocation.

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

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

Schema covers both parameters with descriptions (100% coverage). Description adds that scoped packages ('@types/node') are accepted for 'package', and 'version' defaults to latest published when omitted. Provides extra 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 it's a composite check for npm package evaluation, covering license, advisories, version history, and bundle size. It distinguishes from sibling tools which are unrelated (e.g., AI agents, polymarket). Verb 'scan' + resource 'dependency' is specific.

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

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

Explicitly states when to use: when agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Also notes ecosystem limitations (NPM only in v1) and alternative (deps.dev:version for other ecosystems).

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 adds that the tool is keyless and returns specific fields (tsn, author, kingdom). No contradictions with annotations.

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

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

The description is three sentences, front-loading the core purpose, followed by return fields and usage tip. Every sentence adds value with no wasted words.

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

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

Given the simple single-parameter tool, no output schema, and comprehensive annotations, the description fully covers what the tool does, what it returns, and how to use the result with other tools.

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

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

With 100% schema coverage, the description repeats the parameter's purpose but adds no new semantic detail. The example in the schema already illustrates usage, so 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 states the tool searches ITIS by scientific name and resolves to TSNs, listing return fields. It distinguishes from sibling tools like get_hierarchy and get_common_names by suggesting their use after retrieval.

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 notes the tool is keyless and suggests using the result with get_hierarchy or get_common_names. However, it does not specify when not to use it or alternatives for non-taxonomic queries.

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, etc.) are already clear, but the description adds significant extra behavioral details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K character cap with truncation and flagging. No contradiction with annotations.

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

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

Two clear sentences plus a technical note. Front-loaded with purpose and key use case. No wasted words; every sentence adds value.

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

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

For a read-only, idempotent semantic search tool with no output schema, the description adequately describes return values (top-N passages with offsets and similarity scores), constraints (200K char limit), and pairing instructions. Complements annotations well.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds contextual meaning (e.g., 'text' is 'document text', 'query' is 'natural-language'), but does not provide syntax or format details beyond the schema. Adequate given coverage.

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

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

The description clearly states it performs semantic search inside a fetched record, using a specific verb ('search within') and resource ('source'). It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and the use case for large records.

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 tells when to use it ('when the record is too big to cram into the prompt') and what it pairs with (ask_pipeworx_grounded). It implies when not to use (small records), but does not explicitly list 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 indicate idempotent and non-destructive behavior. The description adds that it creates a subscription, requires OAuth, and includes rate limits (10 SMS/day). No contradictions found.

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

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

The description is well-structured with the main purpose first, then types, then delivery. It is somewhat lengthy but each part adds necessary detail. A minor improvement could be even more concise phrasing.

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

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

Despite no output schema, the description explains the return (subscription ID) and covers all aspects: types, parameters, delivery, constraints, and how to pull alerts. It is thoroughly complete for this complex tool.

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

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

Schema has 100% coverage, and the description enriches it with detailed examples for each type and delivery option, including parameter constraints and behavior (e.g., webhook signing secret returned once).

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 creates a proactive monitoring subscription and returns a subscription ID. It specifies the resource (live-data event stream) and distinguishes itself from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides explicit usage context: requires Pipeworx OAuth account, lists supported subscription types with examples, and explains delivery channels. It does not explicitly state when to avoid using this tool, but the context is sufficient.

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

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

Beyond annotations (readOnly, idempotent), description adds context that it returns live example questions from a catalog and can be focused via topic. No contradictions with annotations; describes non-destructive, safe 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?

Well-structured with front-loaded alternative queries and clear explanation, but slightly verbose with extensive list of categories. Still effective and concise enough.

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

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

Despite no output schema, description fully explains return format (category-bucketed examples with tool+argument shapes). Covers no-arg and with-arg usage, making it complete for onboarding.

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?

Single optional parameter has 100% schema coverage. Description adds examples of valid topic values and explains that omitting gives a cross-category spread, which is more helpful than the schema alone.

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

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

The description clearly states the tool returns category-bucketed example questions and positions it as the onboarding entry point. It distinguishes from sibling tools like ask_pipeworx and discover_tools by emphasizing 'what can I ask' and learning capabilities.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to omit or include the topic parameter. Provides clear context for when to use this tool versus others.

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

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

Goes beyond annotations by detailing ownership enforcement and deactivation (not deletion), ensuring historical events remain via recent_alerts. No contradiction with annotations.

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

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

Two sentences, front-loads purpose, no unnecessary words. Efficient and clear.

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

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

Covers all essential aspects: purpose, ownership, effect on data. No output schema, but return value could be implied. Slightly incomplete but sufficient for simple tool.

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

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

Schema coverage is 100% and description for param 'id' already says it's from subscribe. Description adds no new semantic detail, so baseline 3.

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

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

Description clearly states it cancels a subscription by id, with ownership enforcement and deactivation vs deletion. Distinguishes from sibling tools like subscribe 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?

Explicitly says only own subscriptions can be canceled, implying context. Could be stronger by explicitly stating when to use, but adequate given sibling tool names.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behaviors, so the description adds significant context beyond that: the dual-path routing (SEC EDGAR vs. grounded pipeline), the specific verdict output set, citation requirement, and the crucial caller-facing note distinguishing 'could_not_verify' from 'unsupported' and clarifying that it must not be interpreted as evidence. This is rich, behavior-revealing information.

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 concrete user-phrase examples and a direct usage statement. Although lengthy, every sentence earns its place: two routing paths, output specification, and a clearly structured 'IMPORTANT' caveat. Formatting aids readability without fluff.

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

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

For a two-parameter tool with no output schema, the description is exceptionally complete. It covers input phrasing, routing logic, return value (verdict + value + citation + reasoning), and critical edge-case semantics for 'could_not_verify' and 'unsupported'. The added note about replacing multiple sequential calls contextualizes its role. No operational 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 description coverage is 100%, with both 'claim' and 'tolerance_pct' already fully described. The description reinforces the tolerance semantics ('exact percent-delta math', 'capped at 5') but does not add meaning beyond the schema. Baseline 3 is appropriate when the schema carries the parameter detail.

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

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

The description clearly states the tool's purpose with a specific verb and resource: natural-language claim verification against authoritative sources. It distinguishes this tool from siblings by framing it as the designated fact-checking tool for both company-financial claims (via SEC EDGAR/XBRL) and any other factual claims, with examples of user phrasing.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing direct guidance. It also differentiates when to use the financial fast path vs. the general grounded pipeline. However, it does not explicitly name sibling alternatives or state when NOT to use the tool, so it stops short of a full with/without comparison.

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