Census

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds valuable context: the default model, billing pass-through for Anthropic, and the return structure (per-model score, confidence, signals, raw_response + combined view). No contradictions.

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

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

Two sentences: first explains purpose and output, second covers model options and use cases. No redundant words, front-loaded with the core action.

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

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

For a tool with 4 simple params, complete annotations, and no output schema, the description fully covers what the agent needs: purpose, model selection, optional parameters, and return format. No gaps identified.

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

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

Schema covers 100% of parameters. The description adds meaning beyond schema: specifies default model for 'models', explains that '_apiKey' is only needed for Anthropic and is passed directly, and gives example usage for 'context'. This extra context justifies a 4.

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

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

The description clearly states the action (probe), resource (LLMs for brand/topic knowledge), and output (visibility score 0-100 per model). It also distinguishes from sibling tools by specifying AI-marketing audits and brand checks, differing from query-focused siblings like ask_pipeworx.

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

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

Provides clear context: default free model vs. paid Anthropic with BYO key, and enumerates use cases (AI-marketing audits, pre-launch checks). Lacks explicit when-not-to-use instructions, but the differentiation is sufficient for an agent.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already convey safety and idempotency. Description adds that it routes to 3,745 tools, returns structured answers with stable citation URIs, which are valuable behavioral traits not in annotations. No contradictions.

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

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

Description is moderately long but front-loaded with the key preference statement. Every sentence adds value; no fluff. Could be slightly more concise but justified by the tool's complexity.

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

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

Considering no output schema, description adequately explains return format (structured answer with citations). It covers scope (3,745 tools, 884 sources) and provides examples. Lacks explicit 'when not to use' but given annotations and schema, it's fairly 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?

Input schema has 100% coverage with all 6 parameters aliases for 'question', each described. Description adds examples and context on what kind of questions work, enhancing the schema's meaning.

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

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

Description clearly states the tool's purpose ('PREFER OVER WEB SEARCH for questions about current or historical data'), lists specific domains (SEC filings, FDA data, etc.), and provides examples. It distinguishes from siblings like 'ask_pipeworx_grounded' and 'deep_research' by emphasizing its broad, authoritative data coverage.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and lists trigger phrases ('what is', 'look up', etc.). Gives examples. While no explicit 'when not to use' or sibling differentiation beyond the preference statement, it provides clear guidance on appropriate contexts.

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 hallucination resistance, use of ONLY tool result, explicit refusal reasons (not_in_source, no_tool_match, etc.), output format, and extra LLM call cost. Annotations already show read-only, open-world, idempotent, non-destructive; description adds rich behavioral context beyond annotations.

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

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

Single dense paragraph front-loaded with key concept, then process, output, usage guidance, and cost trade-off. Every sentence adds value, no 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?

Despite no output schema, description explicitly defines return format. Covers purpose, behavior, usage, and output completely. Parameters are simple aliases well described in schema.

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

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

Schema coverage is 100% with all 6 parameters described as aliases for 'question'. Description adds that the tool routes and fills arguments, but does not detail parameter usage beyond what schema provides. Baseline 3 is appropriate.

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

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

Clearly states it is a hallucination-resistant answer mode for high-stakes reads, differentiates from sibling ask_pipeworx by noting extra LLM call and preference for casual lookups. The verb 'ask' and resource 'Pipeworx' are specific, and the description explains the routing and extraction process.

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

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

Explicitly says when to use: when answer will be quoted, cited, or acted on, and agent must not invent facts. Also states prefer ask_pipeworx for casual lookups due to extra cost. Provides clear guidance on 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?

Beyond annotations (readOnly, idempotent), the description discloses resolver contract (match confidence, alternatives), parent event extraction, news fallback mechanisms, safety short-circuits for low-confidence matches, closed market handling, wide spread warnings, and cancellation rule risks. This is exceptional behavioral detail.

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

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

The description is thorough but lengthy, with multiple paragraphs covering many details. It is well-structured (purpose, use cases, examples, safety notes) but could be more concise by grouping some details.

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

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

Given the tool's complexity (resolver, classifier, fan-out, multiple data sources) and no output schema, the description provides comprehensive information on response shapes, error handling, safety, and edge cases. It leaves little ambiguity for the agent.

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

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

Schema coverage is 100% so each parameter already has a description. The tool description adds overall context (e.g., fan-out, resolver) but does not significantly enhance the meaning of individual parameters beyond what the schema provides.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, accepting multiple input formats (slug, URL, question text). It gives specific use cases ('should I bet on X') and covers the full research workflow, 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 lists use cases ('Use for ...') and provides extensive examples of fan-out for different bet types, guiding when to invoke. However, it does not explicitly state when not to use or name alternative tools, though the specificity implies clear context.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds content about return data types but no behavioral context (e.g., rate limits, data freshness, API key requirement). With strong annotations, the description meets the baseline but adds limited value.

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

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

The description is two sentences, front-loads the action, and avoids verbosity. It is appropriately concise but could be more structured (e.g., separate guidelines from examples).

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

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

Given the existence of an output schema, the description need not cover return values. However, it omits the necessity of an API key (though present in schema) and the full breadth of variables retrievable. It is adequate for a tool with good schema and annotations, but not exhaustive.

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 provides 100% coverage with detailed parameter descriptions. The description adds a concrete variable code example and lists result data types, offering marginal semantic enrichment. However, it doesn't resolve ambiguity beyond the schema's existing descriptions.

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

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

The description clearly states the tool searches ACS data by geography and variable code, with a concrete example. It lists returned data types, but doesn't explicitly differentiate from sibling census tools like census_homeownership, which may overlap. The purpose is clear but could be more precise about the generality of variable selection.

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

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

The description provides no guidance on when to use this tool versus sibling tools (e.g., census_homeownership, census_building_permits). It does not mention prerequisites, limitations, or alternative tools for specific tasks. The user is left to infer usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds value by specifying return content (dataset names, descriptions, variable codes) and giving an example code. No contradictions.

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

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

Two concise sentences front-loaded with purpose. No wasted words.

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

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

Complete for a simple discovery tool with no required params and existing output schema. Covers purpose, return type, and example usage.

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

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

Schema coverage is 100%, with one optional param (_apiKey) fully described. Description adds no new parameter info beyond the schema, so baseline of 3 is appropriate.

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

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

Description clearly states the tool discovers Census datasets and variables, returning specific details like variable codes. Distinguishes from sibling census tools (e.g., census_acs) that query data rather than list available datasets.

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?

Implies usage before querying with other census tools, but lacks explicit when/when-not guidance or references to alternatives. Could be improved by stating 'Use this first to find datasets, then use census_acs etc. to query.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds context about monthly periodicity and geographic scope, but does not disclose data freshness, coverage limitations, or behavioral quirks. With annotations covering safety, a 3 is appropriate.

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

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

The description is two sentences, front-loads the action and result, and contains no fluff. Every word contributes to understanding.

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

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

An output schema exists (stated but not shown), so return values need not be explained. However, the description lacks context about typical use cases, data source (Census API), or limitations like key requirements. For a simple query tool it is adequate but not comprehensive.

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 input schema already documents all four parameters with descriptions. The tool description does not add any additional meaning or usage advice beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly states the action ('Check monthly building permits') and resource ('new residential construction by geography'), and specifies what it returns ('count of authorized privately-owned housing units and construction activity trends'). It is self-contained and distinct from siblings like census_housing_starts, though it lacks explicit differentiation.

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

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

The description provides no guidance on when to use this tool versus alternatives such as census_housing_starts or census_acs. It does not specify context, prerequisites, or exclusions, leaving the agent to infer usage from the name alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by stating the data source and return type (percentage), which is consistent with annotations. No contradictions.

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

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

Two sentences, front-loaded with the core purpose, no wasted 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?

Given the simple read-only nature and existence of output schema, the description is fairly complete. It lacks guidance on the missing geography parameter and usage context, but overall adequate.

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 describes both parameters. However, the description mentions 'by geography' but there is no geography parameter in the schema, creating confusion. The description does not add meaningful semantics beyond the schema.

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

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

The description clearly states it checks quarterly homeownership rates by geography and returns a percentage from the Housing Vacancy Survey. It distinguishes itself from sibling tools like census_housing_starts and census_acs.

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

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

No explicit guidance on when to use this tool versus alternatives. The description focuses on what it does but does not mention exclusions or comparison to other census tools.

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

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

Annotations already declare readOnlyHint and non-destructive behavior. The description adds context about the return content (trends, metrics) but does not disclose any additional behavioral traits beyond the schema and annotations.

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

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

Two sentences, front-loaded with verb and resource. Every sentence adds value without 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 read-only data tool with an output schema, the description sufficiently explains what the tool returns (pipeline stages and trends). No additional details are necessary.

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. The description does not add new meaning beyond what the schema provides; it only gives a high-level summary of the variables and geography.

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

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

The description clearly states the tool retrieves residential construction pipeline data including new starts, units under construction, and completed units. It specifies geography as a dimension but does not explicitly differentiate from sibling tools like census_building_permits or census_homeownership.

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

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

No guidance on when to use this tool versus alternatives. The description lacks any indication of when-not-to-use or explicit context for selecting this tool over related census tools.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by detailing specific behaviors: data sources per entity type, handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. This level of detail ensures the agent understands the tool's operational nuances and output format.

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 concisely structured, starting with example queries that immediately convey the tool's purpose. Each sentence adds value: usage guidance, data sources, sorting, and return format. While it is relatively long, it is efficient and front-loaded with the most critical information. Minor trimming could be possible, but it remains effective.

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

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

Given the tool's complexity (multiple entity types, data sources, no output schema), the description covers all necessary aspects: entity types, data sources, fiscal year handling, sorting, and citation URIs. It substitutes for the missing output schema by describing the return format. The context is complete for an agent to select and invoke 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 input schema already provides good parameter descriptions (enum for type, array constraints for values). The description supplements this by explaining what data each type pulls (e.g., revenue, net income, cash for companies; adverse-event counts for drugs) and the sorting behavior. This adds meaningful context beyond the schema, justifying a score above the baseline of 3.

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

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

The description starts with explicit, concrete query examples ('Compare X and Y', 'X vs Y', 'which is bigger', 'rank these companies', 'head to head') that immediately clarify the tool's purpose. It specifies the exact resources compared (companies or drugs) and the data sources (SEC EDGAR/XBRL for companies, FAERS for drugs). It also contrasts with sibling tools by noting it replaces 8–15 sequential 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 explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use this tool instead of alternatives. It also details the two entity types and the data each retrieves, helping the agent determine applicability. However, it does not explicitly state when NOT to use it or provide specific exclusion criteria.

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

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

The annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral context: it decomposes questions, routes to multiple tools in parallel, extracts verifiable findings with citations, and identifies gaps. It also sets expectations for response time (15-60s). No contradictions with annotations.

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

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

The description is relatively long but well-structured, with the core purpose upfront. Each sentence adds necessary information (parallel execution, output format, usage guidance, prerequisites, time expectation). While it could be slightly more concise, it avoids redundancy and maintains 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 that there is no output schema, the description thoroughly explains the return value: a structured findings packet with verbatim evidence, confidence, source, fetched_at, citation, and explicit gaps. It also covers prerequisites, account requirements, and time expectations. For a complex tool like this, the description is highly complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds value by explaining the 'depth' enum values concretely ('quick=3, standard=5 (default), thorough=8 (paid plans)') and clarifying that the 'question' parameter can be broad or multi-part. This enriches the schema information.

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 'Grounded multi-source research in ONE call' and explains the decomposition and parallel routing. It distinguishes itself from the sibling 'ask_pipeworx' tool by noting that deep_research is for broad/multi-part questions, while ask_pipeworx is for single 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 explicitly advises when to use this tool ('Use for broad or multi-part questions') and when not ('use ask_pipeworx for single lookups'). It also mentions prerequisites: a Pipeworx account and a paid plan for 'thorough' depth. This provides clear 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 declare readOnlyHint=true and idempotentHint=true. The description adds value by stating that results include full input schemas with curated examples and are 'ready to call directly, no second schema lookup needed.' No contradiction with annotations.

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

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

Description is well-structured: starts with verb and resource, then usage scenarios, then return value, then directive. Slightly verbose but each sentence adds value. Front-loaded with key 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?

Despite no output schema, the description explains what is returned (names, descriptions, schemas). Parameter count is 6 but many are aliases; the description covers the essential 'query' and 'limit' adequately. Sufficient for a discovery 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 description coverage is 100%, so baseline is 3. The description explains the 'query' parameter's role and mentions 'limit' with default/max, but the schema already provides similar information (including aliases). Limited additional value.

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

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

The description clearly states the function: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and distinguishes from sibling tools which are specific tools, not a meta-tool for discovery.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' Provides clear context, though no explicit exclusions or alternatives are mentioned beyond the implied order of operations.

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

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

Adds value beyond annotations by disclosing patent data source sunset and soft-fail behavior, return field details, and source list. No contradictions with annotations (all read-only, idempotent).

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?

One dense paragraph with front-loaded example queries. Efficient but could be better structured (e.g., bullet points for returns). 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?

No output schema, but description thoroughly enumerates return fields (cik, filings, fundamentals, patents, news, LEI) and data sources, plus failure mode. Complete for a holistic profile tool.

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

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

Schema coverage is 100%, but description adds clarification on CIK zero-padding and reaffirms that names are unsupported. Schema descriptions are adequate, so slight enhancement.

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

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

Description explicitly states 'full cross-source profile of a US public company in ONE parallel call', uses clear verbs like 'profile', and distinguishes from siblings by advising preference over chaining single-source 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?

Provides explicit when-to-use ('when user asks for holistic view'), when-not ('names not supported'), and alternative ('use resolve_entity first'). Clear and actionable.

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

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

Description aligns with annotations: destructiveHint true and readOnlyHint false confirm mutation. Adds context about clearing sensitive data, enhancing transparency.

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, front-loaded sentences: first states purpose, second gives usage guidance. No wasted words.

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

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

For a simple tool with one parameter, complete annotations, and no output schema, the description adequately covers purpose, usage, and parameter meaning.

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

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

Schema covers 100% of the single parameter 'key' with a clear description. Description repeats the concept but adds no extra semantics beyond the schema.

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

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

Description clearly states it deletes a memory by key, which is a specific verb and resource. It also distinguishes from siblings 'remember' and 'recall'.

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

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

Explicitly states when to use (stale context, task done, clear sensitive data) and pairs with 'remember' and 'recall' as alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds that it fetches the page and extracts title/description/key links, which is useful but not extensive. No mention of error handling or rate limits, but annotations mitigate the burden.

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: purpose, mechanism, use cases. It is front-loaded with the most important information and contains no unnecessary words. Every sentence earns its place.

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

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

Given no output schema, the description adequately explains the output. Parameters are well-documented in schema. Use cases are provided. It lacks mention of error handling or edge cases, but for a simple tool this is acceptable. Annotations cover behavioral context.

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

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

Schema description coverage is 100%, with both parameters described. The description adds value by explaining the output format (standard llms.txt markdown) and the fact that the output is a single text blob. This goes beyond the schema but is not per-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: generating a production-ready llms.txt file for any URL. It specifies the action (generate), resource (llms.txt for a URL), and output format (text blob). It distinguishes itself from sibling tools by focusing on llms.txt generation, which no sibling does.

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

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

The description explicitly lists three use cases: getting a client's site indexed, drafting for own project, and auditing competitor AI visibility. This provides clear context on when to use the tool. It does not provide exclusions or alternatives, but the context is sufficient for a unique tool.

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

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

Annotations already cover readOnlyHint, idempotentHint, destructiveHint. Description adds return field list, but no further behavioral disclosure beyond annotations.

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

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

Two sentences, front-loaded purpose, no wasted words. Highly concise.

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

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

No output schema, but description compensates by listing return fields. Annotations cover safety. Minor gap: no mention of pagination or limits, but adequate for a simple list tool.

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

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

Schema covers the single parameter with description. Description does not add meaning beyond schema, 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?

The description clearly states the tool lists the caller's active subscriptions, distinguishes from siblings like subscribe and unsubscribe, and enumerates return fields.

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

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

Provides explicit use cases: review before adding more or to find an id to cancel, guiding when to use. Could explicitly mention when not to use, but adequately 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?

Despite annotations only indicating non-read-only, the description adds valuable behavioral context: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and that the team reads digests daily. These details help the agent understand constraints and impact.

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 yet comprehensive. It front-loads the main action and then efficiently covers usage triggers, behavioral constraints, and formatting tips. 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?

Given the tool has 3 parameters (2 required), a nested object, no output schema, and moderate complexity, the description covers all necessary aspects: purpose, triggers, parameter semantics, constraints, and expected input format. 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 coverage, baseline is 3, but the description adds significant meaning: explains the enum values in 'type', provides formatting guidance for 'message' (be specific, 1-2 sentences, 2000 chars max), and clarifies the 'context' object is optional with examples (pack slug, tool name, vertical). This goes well beyond the schema.

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

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

The description explicitly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It lists specific feedback types (bug, feature, data_gap, praise) and clearly differentiates from sibling tools by being a feedback channel, not a data retrieval or analysis tool.

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

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

The description gives clear guidance on when to use each feedback type (e.g., 'Use when a tool returns wrong/stale data (bug)') and what not to do ('don't paste the end-user's prompt'). It does not explicitly mention alternatives to this tool, which is appropriate given its unique role.

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, non-destructive. Description adds valuable context: data source (CF analytics-engine), privacy (no PII), and caching policy (5min-1h). No contradictions.

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

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

Description is concise, front-loaded with the core function, followed by use cases and technical details. No redundant sentences.

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

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

No output schema, but description explains what is returned (top tools, packs, call volume) and mentions caching. For a read-only tool with good annotations and simple output, this is sufficiently complete.

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

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

Schema coverage is 100% with descriptions for the single optional parameter. Description adds context about window behavior ('shorter windows surface hot, longer show steady-state'), which enriches the enum choices.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over recent windows. It distinguishes itself from sibling tools by focusing on trending/aggregated data, which no other sibling tool covers.

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

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

Explicitly lists three use cases for the tool, and hints at window selection (short vs long). Lacks explicit 'when not to use' or alternatives, but the use cases are specific enough to guide the agent.

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

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

Describes detailed algorithm behavior: monotonicity checks, partition sum verification, QJaccard similarity threshold, placeholder filtering, and fill-check against CLOB depth. The description adds substantial behavioral context beyond annotations, which already indicate read-only and idempotent properties.

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 comprehensive but somewhat lengthy; however, every sentence contributes useful information. The key information (requirement, modes) is front-loaded. Could be slightly more concise but effective overall.

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

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

Despite no output schema, the description explains the response structure (opportunities array, partition_check, fill_check) and references the sibling tool for further detail. All aspects of usage, parameters, and behavior are covered, making the description self-sufficient for an agent.

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

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

Both parameters 'event' and 'topic' are fully described in the input schema (100% coverage). The description enhances these by explaining their recommended use cases and providing example inputs, adding significant semantic 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?

Description clearly identifies the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with concrete examples, making the purpose specific and distinct from sibling tools.

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

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

Explicitly states the requirement of providing either 'event' or 'topic', warns against calling with no args, and recommends event mode for specific markets versus topic for cross-event scanning. It also references sibling tool 'polymarket_fill_risk' for custom sizing, providing clear when-to-use guidance.

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

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

Goes far beyond annotations (readOnly, openWorld, idempotent, non-destructive) by detailing caching at 1h KV level, edge calculation including slippage and Kelly fractions, three segment models, and diagnostics for empty segments. 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?

Compact yet comprehensive; front-loaded with purpose, then segments, fields, knobs, response structure, and caching. Every sentence is informative 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?

Given the complexity (9 params, no output schema), the description fully compensates by thoroughly explaining response structure, edge fields, knobs, and diagnostics. Leaves no gaps for agent understanding.

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

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

Schema coverage is 100% so schema already documents parameters well. The description adds value by explaining the rationale behind knobs (min_partition_leg_kelly nuance, min_kelly not filtering partition arbs) and how they interact.

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

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

The description clearly states it scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, explicitly built for 'what should I bet on today' and distinctly different from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on three specific segments.

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 strong context for when to use (discovering betting opportunities) and explains three segments and tradeable-edge knobs. Lacks explicit 'when not to use' or direct alternatives, but the detail on segments and knobs gives good guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it works from daily snapshots, bounded by 60-day TTL, decay computed from daily closes (not intraday), and response structure. 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 fairly long but well-structured: starts with purpose, then response breakdown, then limits. Every sentence adds value, though slightly more concise could improve. Still, it is efficiently organized.

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

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

No output schema exists, but the description details the response shape (tracked[], expired[], snapshot_dates[]) and mentions limitations (60-day TTL, daily closes). This fully compensates for missing schema and provides complete contextual understanding.

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

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

Input schema covers 100% of parameters with descriptions. The description enhances meaning: days lookback default 14 max 30, window snapshot family default '1wk', and explains snapshots are written on cache-miss, adding 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?

The description clearly states the tool provides 'edge persistence and decay telemetry from daily polymarket_edges snapshots.' It distinguishes from siblings by explaining the key difference: a fresh wide edge versus a 3-week-old wide edge are different trades, which separates it from raw edge tools like polymarket_edges.

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

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

The description specifies when to use the tool: answers 'how long has this edge existed and is it shrinking?' It implies usage context but does not explicitly state when not to use or name alternative tools. However, the distinction between edges of different ages provides clear 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 declare idempotent/read-only; description adds details about walking the ladder, fill mechanics, and risk warnings (thin books, partial fills) not covered by annotations.

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

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

Well-structured with REQUIRES, mode sections, and usage note; every sentence adds value, though slightly long but justified by complexity.

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

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

Despite no output schema, the description enumerates all returned fields and covers prerequisites, behavioral details, and risk warnings completely for an agent to use correctly.

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

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

Schema covers 100% parameters with descriptions; description adds mode-specific semantics (side default in basket, size_usd interpretation for buys vs sells) and lists returned fields, significantly augmenting 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 checks realizable vs theoretical edge against CLOB depth, details two modes (single-market and basket), and distinguishes from siblings by specifying when to use (before arb/edge signals).

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

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

Explicitly tells when to use: before acting on polymarket_arbitrage sell/buy-every-leg or edge trades above ~$500, and warns about thin books and partial basket fills becoming directional positions.

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

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

The annotations declare readOnly, openWorld, and idempotent hints. The description goes well beyond by detailing two modes, the response structure including top_spreads_pp, compatibility_warning conditions, temporal_alignment, and skipped cross-type counters. No contradictions with annotations.

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

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

The description is detailed but well-structured with clear sections for modes, response, and safety fields. Every sentence provides value. Minor redundancy (e.g., repeated mention of compatibility warning) but overall concise for the complexity.

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

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

Given the three parameters and no output schema, the description thoroughly explains the tool's behavior, response fields, and edge cases. It covers compatibility warning, temporal alignment, and skipped counters, making it nearly self-contained despite the lack of an output schema.

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

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

Schema coverage is 100% and the description adds significant meaning: it explains the two modes, the topic macro shortcuts, and the explicit override behavior. It also describes the response fields, which compensates for the lack of an output 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 computes cross-venue spreads between Kalshi and Polymarket for the same outcome, and describes two operational modes. It does not explicitly distinguish it from the sibling 'polymarket_arbitrage', but the name and context make the purpose clear.

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

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

The description explains when to use (when interested in cross-venue price differences due to participant pool divergence) and warns about non-equivalent bet shapes and temporal misalignment making spreads invalid. It notes that pre-mapped topics often yield compatibility warnings, providing realistic expectations. No explicit alternatives, but the guidance is sufficient.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds valuable context: listing all keys when key omitted, scoping by identifier, and pairing behavior. 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, each essential: first states action, second gives use cases, third explains scoping and relationships. Front-loaded with key operation. No extraneous words.

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

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

Given low complexity (1 optional param, no output schema), the description covers purpose, usage, behavior, and relationships. Could mention error handling for missing key, but not critical.

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

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

Schema has 100% coverage with a description for the key parameter. Description reinforces the dual behavior (value vs list), adding clarity beyond the schema. Slight improvement over baseline 3.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all keys when no key is provided. It distinguishes from siblings by naming 'remember' and 'forget' 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?

Provides explicit guidance: when to use (look up context stored earlier), what for (ticker, address, notes), scoping (by identifier), and pairing with remember/forget. Also implies when not 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 already declare readOnly, openWorld, idempotent, and non-destructive. The description adds useful behavioral context: the mark_read mechanism to flag events as read, the kind of data returned, and that polling is acceptable. It does not cover error conditions or open-world implications, but adds value beyond annotations.

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

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

The description is two sentences, front-loaded with purpose and key data, then adds filtering and behavior details. Every sentence earns its place, 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?

Given 5 optional parameters and no output schema, the description covers the main return fields (source, citation_uri, payload), filtering options, mark_read behavior, and polling suitability. It misses explicit details on unread_only parameter and limit behavior, but overall is well-rounded for a safe, idempotent retrieval tool.

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

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

Schema coverage is 100% with parameter descriptions, so baseline is 3. The description adds extra meaning: it provides an example for 'type' ('sec_8k'), explains 'since' as ISO timestamp, and describes the purpose of 'mark_read' to advance the feed. This enhances understanding beyond the schema alone.

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

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

The description clearly states the verb-resource pair: 'Pull fired events from your subscription feed.' It specifies the return fields (source, citation_uri, raw event payload) and distinguishes this tool as a read-only alert retrieval, with no sibling alert tools to confuse.

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

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

The description provides clear context on when to use: for accessing most recent alerts, filtering by type and/or time, and using mark_read to advance the feed. It mentions polling works fine and gives an alternative HTTP endpoint. However, it does not explicitly state when to avoid this tool or compare to alternatives, but given no siblings, this is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds value by detailing fan-out to multiple sources (SEC EDGAR, GDELT/GNews, USPTO) and soft-fail behavior for PatentsView. No contradiction with annotations.

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

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

Description is well-structured and front-loaded with examples. It is slightly verbose but every sentence adds value, explaining sources, fallback, and return structure.

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

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

Without an output schema, description explains the return format (changes[] grouped by source, total_changes count, citation URIs). It also covers source behaviors and soft-fail, making it complete for a complex aggregation tool.

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

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

Schema coverage is 100% with descriptions for all three parameters. Description supplements with examples for 'since' (ISO date, relative shorthand like '7d', '30d', '3m', '1y') and clarifies that 'type' only supports 'company' currently, adding practical usage context.

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

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

Description clearly states it provides a change feed for a company over a window, with multiple example queries ('What's new with X', 'latest on Y'). It distinguishes from sibling 'entity_profile' by specifying when to use the alternative tool.

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

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

Explicitly says when to use this tool vs 'entity_profile' for static profile. Also describes fallback behavior from GDELT to GNews when rate-limited or 5xx, providing clear context for usage.

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

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

Annotations indicate idempotent and non-destructive behavior. Description adds key-value scoping by identifier and session persistence details. Does not mention overwrite behavior but overall transparent.

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

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

Four concise sentences, each earning its place: purpose first, then usage guidance, then storage details, then pairing with siblings. No wasted words.

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

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

For a simple store tool, description covers purpose, usage, persistence, and pairing. No output schema needed; parameters fully described. Complete for an agent to use correctly.

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

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

Schema coverage is 100%, so schema already describes parameters. Description adds helpful examples for key naming conventions and clarifies value accepts any text, 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 saves data for reuse across conversations and sessions, with specific examples like resolved ticker, target address, user preference. It distinguishes from sibling tools recall and forget.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward'. Also advises pairing with recall and forget, and explains persistence differences for authenticated vs anonymous sessions.

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

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

Annotations already indicate safe read-only, idempotent behavior. The description adds substantial behavioral context: internal cascading through multiple endpoints, auto-disambiguation for companies, and specific return fields per entity type. This goes beyond the annotations to fully inform the agent.

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, front-loaded with purpose and examples, then details per type. While comprehensive, it could be slightly more concise by omitting the repeated 'what's the...' examples. Still, it efficiently conveys necessary 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?

Despite lacking an output schema, the description fully explains return values for both entity types, including citation URIs and fields. It also covers internal behavior (cascading lookups) and input flexibility, making the tool's behavior completely clear.

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 param descriptions, but the tool description enriches semantics by explaining accepted input formats (e.g., ticker, CIK, or name for company) and the resulting output for each type, which is not in the schema. This adds significant value.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers needed by other tools. It provides concrete examples like 'What's the ticker for...' and specifies supported types (company, drug) with detailed output fields, distinguishing it from sibling tools that likely require IDs.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear context for when to use. It lacks explicit when-not-to-use guidance or alternative tool references, but the context of needing an ID before other tools is well-implied.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds that it probes each entity with ai_visibility_check, ranks results, and returns per-entity details. It does not mention potential failures or rate limits, but sufficient given the annotation coverage.

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

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

The description is three sentences: front-loaded with main action (compare, probe, rank), then use case example, then return value. 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?

No output schema exists, so the description properly explains the return format (ranked list with score, confidence, signal density). It also covers the probe mechanism and use case, making the tool self-contained.

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% description coverage. The description adds value by explaining the ordering of entities (first as subject) and the default model (workers-ai). This goes beyond what the schema provides.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking by score. It distinguishes from sibling 'ai_visibility_check' which is a single entity probe, providing a specific verb and resource.

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 context for competitive AI-marketing audits with an example question. It implies when to use this tool for comparing multiple entities, but does not explicitly exclude single-entity cases or contrast with sibling 'compare_entities'.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds transparency about the tool's composite nature, its reliance on external services (deps.dev, bundlephobia), and potential delays (5-30s for first bundlephobia measurement). It also explains partial failure behavior. This adds value beyond annotations, though not all edge cases are covered.

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

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

The description is fairly long but well-structured. It front-loads the core purpose and gradually adds details (sources, usage, limitations, behavior). Every sentence contributes meaning. Minor redundancy (e.g., mentioning 'NPM ecosystem only in v1' twice) could be trimmed, but overall it's concise given the complexity.

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

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

Despite having no output schema, the description lists the returned fields (summary block, per-advisory detail, links, alternative versions). It covers the tool's composite nature, external dependencies, failure behavior, and ecosystem scope. This is comprehensive for a tool of this 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 description coverage is 100% (both parameters documented). The description adds clarifying details: package accepts scoped packages (e.g., '@types/node') and version defaults to latest when omitted. These enhance understanding beyond the schema descriptions, though the additional value is modest.

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

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

The description clearly defines the tool as a composite check for npm packages, specifying the sources (deps.dev and bundlephobia) and the type of questions it answers (safety, popularity, size). It distinguishes this tool from others by noting the ecosystem limitation (NPM only) and pointing to alternatives for other ecosystems.

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

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

The description explicitly states when to use the tool ('whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'') and what to do for non-NPM ecosystems ('fall under deps.dev:version directly'). It also mentions the possibility of partial failures and graceful degradation, providing clear context for invocation decisions.

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 all relevant behaviors: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. Annotations already indicate readOnly, idempotent, non-destructive; description adds rich technical detail beyond annotations.

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

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

Three efficient sentences: first states core function, second explains use case and benefits, third gives technical details. No wasted words, well structured, and front-loaded.

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

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

Given complexity (semantic search with specific embeddings and chunking) and no output schema, description fully explains what is returned (top-N passages with character offsets and similarity scores) and flags truncation. Completely addresses behavioral and return contexts.

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

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

Schema covers 100% of parameters with descriptions. Description adds value by providing examples for query ('supply-chain risk', 'fiscal year 2024 revenue') and clarifying text as 'document text', limit range (1-20, default 5).

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 performs semantic search inside a fetched record, with specific examples (SEC 10-K, article). It distinguishes itself from sibling tools like ask_pipeworx_grounded by explaining how they pair.

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

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

Provides explicit when-to-use guidance: 'when the record is too big to cram into the prompt' and explains it saves context. Mentions pairing with ask_pipeworx_grounded for grounded reasoning. No explicit when-not-to-use, but context is clear.

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

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

The description adds significant behavioral context beyond annotations, such as the requirement for OAuth, delivery channel constraints (SMS 10/day cap, webhook auto-disable after 10 failures), and verification steps for SMS. It does not contradict annotations.

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

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

The description is relatively long but well-structured, with the main purpose stated first, followed by requirements and examples. Every sentence adds meaningful information, though it could be slightly more concise.

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

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

Given the complexity of three parameters, nested objects, and multiple delivery channels, the description covers essential aspects: auth requirements, type-specific parameters, delivery options with constraints, and the return value. No output schema exists, but the description mentions the subscription id is returned.

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 has 100% coverage with descriptions for each parameter, but the tool description adds valuable semantic detail: examples for each subscription type, constraints on delivery parameters (e.g., phone must be verified), and explanation of the webhook signing secret. This enhances understanding 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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by specifying that it is for creating 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?

The description provides clear context for when to use the tool, including the requirement of a Pipeworx OAuth account and that anonymous/BYO cannot persist subscriptions. However, it does not explicitly state when not to use it or compare to alternatives like recent_alerts for pulling alerts.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about return format (category-bucketed example questions with exact tool + argument shape) and optional topic filtering, but does not reveal additional behavioral traits beyond what annotations imply.

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 that front-loads common user queries. While slightly lengthy, every sentence adds value—covering purpose, examples, usage instructions, and parameter details. Could be more structured, but remains efficient.

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

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

Given the tool has only one optional parameter and no output schema, the description is fully adequate. It explains the tool's purpose, when to use it, what it returns, and the effect of the parameter. Annotations cover safety and idempotency, leaving 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 a detailed description of the 'topic' parameter listing all valid values. The description adds nuance by explaining the effect of omitting the parameter ('full spread') versus specifying a topic, which aids usage 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 returns category-bucketed example questions for various domains, positioning it as an onboarding entry point. It distinguishes from sibling tools like ask_pipeworx and entity_profile by focusing on suggestion generation.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains calling with no arguments for full spread or with topic to focus, providing clear 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?

The description discloses that subscriptions are deactivated rather than deleted, preserving historical events. This adds context beyond the annotations (which indicate non-destructive, idempotent behavior) and helps the agent understand side effects.

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

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

The description is extremely concise with two sentences that cover the action, constraints, and effect. Every sentence adds essential information 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?

Given the simplicity of the tool (one parameter, clear annotations, no output schema), the description adequately covers the behavior and constraints. It could optionally describe the return value, but it's not necessary 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?

The single parameter 'id' is fully described in the schema (100% coverage). The description does not add additional semantic value beyond referencing the subscription id returned by 'subscribe', but it is sufficient given the 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 clearly states the action ('Cancel a subscription by id') and the resource (subscription). It also specifies ownership enforcement, distinguishing it from related 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?

It explicitly states when to use this tool ('only cancel your own subscriptions') and provides context about the effect (deactivation, not deletion), guiding proper usage. However, it does not explicitly mention alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description complements these by detailing the underlying data sources (SEC EDGAR + XBRL), the exact verdict types (confirmed, approximately_correct, etc.), and the output structure (structured form, actual value with citation, percent delta). No contradictions with annotations.

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

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

The description is well-structured, starting with common query patterns, then stating the mission, followed by scope and output details. It is concise yet informative, with no wasted sentences. Every sentence adds value.

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

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

Given the absence of an output schema, the description adequately covers the return values (verdict types, structured form, actual value, citation, delta). It also explains the data source and scope. Minor improvements could include error handling or rate limits, but overall it is sufficiently complete for an agent to use the tool correctly.

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

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

There is only one parameter (claim) with 100% schema description coverage. The description adds examples of valid claim formats, which provides additional guidance beyond the schema's description. While the schema already defines the parameter, the examples help clarify expected input.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, with specific examples of queries and the domain (company-financial claims). It distinguishes itself by replacing multiple sequential calls, making the purpose highly specific and unambiguous.

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

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

The description provides a clear when-to-use directive: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also scopes the tool to company-financial claims via SEC EDGAR + XBRL, which implicitly limits usage. However, it does not explicitly mention alternatives for non-financial claims or 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.