Nass

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

Beyond annotations (read-only, idempotent), the description adds that Anthropic calls require a BYO key and incur direct cost, and details the return structure (score, confidence, signals, raw_response) not in output schema.

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

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

Two sentences with no wasted words. The core purpose is front-loaded, and all critical details are included concisely.

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

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

With 4 parameters and no output schema, the description covers return structure and key behavioral notes. Minor gaps (like error handling) but sufficient for the tool's complexity.

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

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

Schema coverage is 100% with descriptions. The description adds value by explaining default model behavior, the pass-through of _apiKey, and examples for context, enhancing parameter understanding.

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

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

The description clearly states the verb 'Probe' and resource 'LLMs' for knowledge about an entity, scoring visibility per model. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by being more general for audits and checks.

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

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

The description provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains default vs Anthropic models with API key. It lacks direct comparison with siblings but gives 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?

Describes that Pipeworx picks the right tool and fills arguments, disclosing its orchestration behavior. With no annotations, this provides essential behavioral context about dynamic routing. Could add more about potential latency or error handling.

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

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

Three sentences: purpose, mechanism, and three clear examples. No wasted words, front-loaded with the core value proposition.

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

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

Given the tool's simplicity (1 param, no output schema), the description is complete enough. Examples illustrate usage well. Could mention that it may use multiple data sources or that results are from the best available source at the time.

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% for the single parameter 'question', so baseline is 3. Description adds minimal extra meaning beyond the schema, just says 'in natural language' which is already implied by the description and examples.

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

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

Clearly states the tool answers plain English questions using best available data source, with specific verb ('Ask a question') and resource ('best available data source'). Examples distinguish from sibling tools that are domain-specific (nass_*, discover_tools, etc.).

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 to describe needs without browsing tools or learning schemas, implying use when you want a natural language query. Does not explicitly say when not to use or mention alternatives, but context signals and sibling names (like nass_* tools) imply alternatives for specific data domains.

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 explains that the tool resolves the market, classifies the bet, fans out to appropriate data packs, and returns an evidence packet with comparison. This adds context beyond the annotations (readOnlyHint, openWorldHint). 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 brief (3-4 sentences) yet comprehensive. It is front-loaded with the main purpose and each subsequent sentence adds specific detail without redundancy. No wasted words.

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

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

Given the tool's complexity (fan-out to multiple packs) and the absence of an output schema, the description adequately explains the return value. However, it does not address potential error scenarios (e.g., market not found) or the possibility of empty results. A brief note on edge cases would improve completeness.

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

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

Schema coverage is 100%, and the description adds semantic value: for 'market', it describes the three input formats (slug, URL, question text); for 'depth', it explains the difference between 'quick' (2-3 sources) and 'thorough' (full fan-out) and states the default ('thorough'). This goes beyond the simple enum descriptions.

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

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

The description clearly states the tool's purpose: researching a Polymarket bet by pulling Pipeworx data in one call. It specifies the input types (slug, URL, question text) and output (evidence packet with market-vs-model comparison), distinguishing it from sibling tools that may require separate data pack 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?

Explicit usage examples are provided: 'should I bet on X?', 'what does the data say about this Polymarket market?', 'is there edge in this bet?'. It also notes that this is the core demo product and that agents using it convert better, giving clear guidance on when to invoke this tool.

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

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

No annotations are provided, so the description carries full burden. It mentions data sources (SEC EDGAR, FDA) and return format (paired data + URIs), but lacks details on rate limits, data freshness, error handling for missing entities, or permission requirements. Behavioral traits beyond function are minimally disclosed.

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

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

Description is two sentences, no fluff. First sentence states purpose and type-specific returns; second adds efficiency claim and return format. Every sentence earns its place, front-loaded with critical 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?

No output schema, so description should explain return structure. It vaguely mentions 'paired data + resource URIs' but does not specify format, ordering, or how fields are presented. Given the tool compares multiple entities with diverse fields, more detail is needed for completeness.

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

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

Schema has 100% coverage with descriptions for both parameters. The description adds meaningful context beyond schema: it explains that type determines which fields are returned, gives example values for values parameter (e.g., ["AAPL","MSFT"]), and specifies constraints (2–5). This adds value without redundancy.

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 2–5 entities side by side, specifies different data fields for company (revenue, net income, etc.) and drug types (adverse-event counts, FDA approvals), and explicitly distinguishes it from sequential agent calls. This is a specific verb+resource with clear sibling differentiation.

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

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

The description implies efficient batch comparison ("Replaces 8–15 sequential calls") but does not explicitly state when to use vs. alternatives like resolve_entity or other data tools. No when-not-to guidance is provided, only inferred 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?

With no annotations provided, the description must disclose behavioral traits. It explains that the tool returns 'the most relevant tools with names and descriptions' and implies it is a search/retrieval tool. It does not explicitly state it is read-only or non-destructive, but the nature of searching a catalog is inherently non-destructive. A minor gap is not mentioning if it has any side effects or rate limits, but for a search tool this is acceptable.

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 long, each adding value: first sentence states the action, second sentence describes the return, third sentence gives usage guidance. No fluff or repetition.

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

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

Given the tool's simplicity (2 params, no output schema, no nested objects), the description is complete. It explains the purpose, return value, and when to use it. However, it does not mention what happens if no tools match or the behavior of the limit parameter beyond schema defaults. Still, for a search/discovery tool, this is sufficient.

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

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

Schema description coverage is 100%, so both parameters ('query' and 'limit') are already described in the input schema. The description does not add additional meaning beyond what the schema provides, such as format requirements or default behavior. The baseline of 3 is appropriate since the schema already does the heavy lifting.

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

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

The description uses a specific verb ('Search') and resource ('Pipeworx tool catalog'), and clearly distinguishes the tool's purpose: it's for discovering relevant tools when many are available, as indicated by 'Call this FIRST when you have 500+ tools available'. This differentiates it from sibling tools which are domain-specific query tools.

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

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

The description explicitly states when to use this tool: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' It implies this is a preliminary step before using specific tools like nass_* or ask_pipeworx, though it does not list explicit alternatives. The 'FIRST' emphasis is 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?

With no annotations, description carries full burden. It discloses that the tool returns pipeworx:// citation URIs, mentions composite nature (replaces many calls), and notes performance issue for federal contracts. Does not explicitly state if read-only, but likely implied.

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, no wasted words. Front-loaded with purpose. Efficiently conveys key information.

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

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

Given no output schema, description explains return type (pipeworx:// URIs) and lists data categories. Covers input constraints and hints at composite nature. Could mention error cases but not necessary for completeness.

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

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

Schema coverage is 100% with descriptions. Description adds value beyond schema: explains value can be ticker or CIK, provides examples, and specifies that names are not supported, guiding use of resolve_entity.

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 returns a full profile of an entity across multiple packs in one call. Provides specific examples of data included (SEC filings, XBRL, patents, news, LEI). Distinguishes from sibling tools like resolve_entity and compare_entities, and mentions replacing 10-15 sequential calls.

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: when you need a full company profile. Also says when not to use: for federal contracts, call usa_recipient_profile directly. Provides prerequisite guidance: if you have only a name, use resolve_entity first.

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?

No annotations are provided, so the description carries the burden. It states deletion but does not disclose whether deletion is permanent, reversible, or requires specific permissions. However, the tool is simple (one required param) and the operation is obvious.

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, concise sentence that is front-loaded and contains no unnecessary words.

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

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

Given the simplicity of the tool (one required parameter, no output schema), the description is sufficiently complete. It clearly states what the tool does and what parameter is needed.

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

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

Schema description coverage is 100% and the parameter 'key' is described in the schema. The description adds no additional meaning beyond the schema, but baseline is 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 verb 'Delete' and the resource 'a stored memory by key'. This distinguishes it from siblings like 'remember' (store) and 'recall' (retrieve).

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

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

The description implies use when you need to delete a memory. It does not explicitly mention when not to use it or alternative tools, but the purpose is clear and distinct from siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details like fetching the page, extracting title/description/key links, and emitting standard markdown format, which goes beyond annotations. No contradictions.

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

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

The description is concise (two sentences plus a bulleted list of use cases) and front-loaded with the main action. Every sentence adds value with no redundancy.

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

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

The description covers inputs, process, output format, and use cases. Without an output schema, it adequately describes the return value (single text blob). It could mention limitations like internet requirements, but overall it is complete for the tool's complexity.

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

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

Schema coverage is 100% with clear descriptions for both parameters (url and max_links). The description does not add new information beyond what the schema already provides, so it meets the baseline but does not exceed it.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb and resource. It distinguishes itself from siblings by focusing on AI crawler indexing, which is unique among the listed tools.

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

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

The description lists concrete use cases (getting client's site indexed, drafting for own project, auditing competitors), providing clear context for when to use. It does not explicitly state when not to use or mention 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?

No annotations are provided, so the description carries the full burden. It states pre-filtering to source=SURVEY and sector=CROPS, which is useful behavioral context. However, it does not disclose potential rate limits, data freshness, or whether it requires specific authentication beyond the API key. The description is adequate but not comprehensive.

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 only two sentences that are front-loaded with the main purpose. Every sentence provides useful information without waste.

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

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

Given the tool has no output schema and moderate complexity (5 params, 2 required), the description covers the core purpose and pre-filtering. It lacks details on output format or potential edge cases, but for a data retrieval tool, it is reasonably 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 baseline is 3. The description adds value by clarifying the pre-filtering context and listing example crop names, which helps with parameter selection. It does not repeat the schema but provides additional semantic context.

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

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

The description uses a clear verb ('Get') and specific resource ('US crop production data'). It distinguishes from siblings by noting it's a 'shortcut for querying NASS survey data on crop yields, production totals, and planted/harvested acreage' and explicitly states pre-filtering to source=SURVEY, sector=CROPS, which differentiates it from nass_livestock and nass_prices.

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 implicitly indicates when to use this tool (for crop production data from NASS survey) and mentions pre-filtering, but does not explicitly state when not to use it or provide alternatives like nass_query for more general queries. However, given the sibling tools, it is clear this is for crop-specific data.

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

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

Annotations are empty, so the description must disclose behavior. It mentions pre-filtering (source=SURVEY, freq=WEEKLY) and the API key requirement, which is useful. However, it does not describe what happens on invalid input, rate limits, or response format (e.g., data structure, pagination). The tool likely returns data, but no behavioral traits beyond the pre-filters are disclosed.

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

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

The description is two sentences: the first clearly states the tool's purpose and data scope, the second adds pre-filtering context. No redundant or unnecessary text. Front-loaded with actionable 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?

Given 4 parameters, no output schema, and no annotations, the description is reasonably complete. It explains the pre-filtering, required parameters, and the type of data returned. It could mention that output is a table-like structure or that errors occur without a valid API key, but overall it provides sufficient context for a simple data retrieval tool.

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

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

Schema coverage is 100%, so parameters are fully documented. The description adds context that the data is pre-filtered (source=SURVEY, freq=WEEKLY), but does not elaborate on parameter values (e.g., valid state names) beyond what the schema says. This is baseline value given high 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 explicitly states the tool retrieves 'weekly crop progress and condition reports' and lists specific data points (planting progress, emergence, blooming, harvest completion, crop condition ratings). It clearly identifies the resource (crop progress reports) and the verb (get). The pre-filtering info distinguishes it from other NASS tools like nass_crop_production or nass_prices.

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

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

The description implies usage for retrieving weekly progress data but does not explicitly state when to use this vs. alternatives like nass_crop_production (production) or nass_query (custom queries). No exclusion criteria or alternative recommendations are provided.

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

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

With no annotations, the description partially discloses behavior: it mentions pre-filtering to 'ANIMALS & PRODUCTS' sector. However, it does not explain whether the tool is read-only or any side effects (likely none). The 'Get' verb suggests read, but without annotations, more detail would help.

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, concise sentence that front-loads the purpose and includes a key detail about pre-filtering. No redundant information.

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

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

Given no output schema and no annotations, the description could provide more context about return structure or additional behavior. However, it adequately describes the tool's purpose and parameters for a data retrieval tool.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description adds no additional semantics beyond 'pre-filtered to sector=ANIMALS & PRODUCTS', which relates to the default sector but is not a parameter. Baseline 3 is appropriate.

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

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

The description clearly states the tool gets US livestock data and lists specific data types (inventory counts, slaughter numbers, production) and pre-filtering (sector=ANIMALS & PRODUCTS). This distinguishes it from other NASS tools like nass_crop_production and nass_prices.

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

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

The description implies use for livestock data but does not explicitly state when to use this tool versus siblings like nass_crop_production or nass_query. There is no guidance on when not to use it or alternative tools.

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

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

With no annotations, the description carries the full burden. It discloses the pre-filters (source and stat_category), which is helpful. However, it does not mention response format, pagination, rate limits, or whether the tool is read-only (likely but unstated). No contradiction with annotations since annotations are empty.

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, consisting of two sentences with no wasted words. It front-loads the core purpose and adds specific pre-filter details efficiently.

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 4 parameters (100% schema coverage), no output schema, and no annotations, the description is adequate but not complete. It explains the pre-filters and optionality of state/year, but lacks details on return values, error conditions, or data ranges. Adequate for a straightforward data 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 description coverage is 100%, so all parameters have descriptions. The description adds pre-filter context but does not provide additional semantics beyond what the schema already says. The commodity parameter lists valid values in the description, but these are also in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves prices received by US farmers for crops and livestock, and distinguishes it from siblings by specifying pre-filters (source=SURVEY, stat_category=PRICE RECEIVED). It does not explicitly differentiate from sibling tools like nass_crop_production, but the pre-filters provide some context.

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

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

The description mentions pre-filters and that state is optional (defaults to national), which helps with usage. However, it does not provide explicit guidance on when to use this tool versus alternatives like nass_query or nass_crop_production, nor does it mention any limitations or prerequisites beyond the API key.

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?

No annotations are provided, so the description carries full burden. It mentions the source (USDA NASS Quick Stats) and that results include various agricultural data. However, it does not disclose important behavioral traits like API key requirement (already in schema), rate limits, pagination, or data freshness. With 0 annotations, more behavioral detail would be expected for a higher score.

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

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

The description is a single, well-structured paragraph of two sentences. The first sentence immediately states the tool's purpose and source, and the second expands on capabilities and outputs. No superfluous information; every sentence earns its place.

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

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

Given 10 parameters, 100% schema coverage, no output schema, and no annotations, the description provides a high-level overview that complements the schema. It explains what the tool returns (production, yield, etc.), which is not in the schema. However, it does not mention response structure, error handling, or usage limits, which would make it complete 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%, so baseline is 3. The description adds value by summarizing the overall purpose and return types, but does not provide additional semantics for individual parameters beyond what the schema already says (e.g., 'commodity' is exemplified, but not further explained). It neither adds nor detracts meaningfully from the schema.

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

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

The description clearly states the tool queries USDA NASS Quick Stats, a comprehensive source of US agricultural statistics. It explicitly lists what the tool supports (filtering by commodity, statistic category, geography, year) and what it returns (production, yield, acreage, prices, livestock, etc.), distinguishing it from sibling tools like nass_crop_production or nass_prices which are narrower.

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

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

The description implies when to use this tool: when needing comprehensive agricultural statistics from USDA NASS. It contrasts with sibling tools by being 'the most comprehensive source', suggesting alternatives for specific domains. However, it does not explicitly state when not to use it (e.g., for very specific crop progress data, nass_crop_progress might be better), which would elevate the score.

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?

With no annotations provided, the description carries the full burden. It discloses that the tool sends feedback, is rate-limited to 5 messages per identifier per day, and advises on content. However, it does not describe the response behavior (e.g., confirmation) or any side effects beyond sending.

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 short and front-loaded, stating the purpose and use cases in the first sentence, followed by constraints. Every sentence contributes useful 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 tool's simplicity (no output schema, 3 params) and no annotations, the description covers essential aspects: purpose, content rules, and rate limits. It does not explain the return value, but for a feedback tool this is acceptable.

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

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

The schema has 100% coverage with descriptions for all parameters. The description adds value by reinforcing the context object's purpose and reminding about the 2000 char limit, but these are already in the schema. The extra rule about not including user prompts is helpful but minor.

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: sending feedback to the Pipeworx team. It lists specific use cases (bug reports, feature requests, missing data, praise) which distinguishes it from sibling tools like ask_pipeworx (likely Q&A) and other data tools.

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

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

The description provides explicit guidance on when to use the tool (bug reports, feature requests, etc.) and what to avoid (not including the end-user's prompt verbatim). It also mentions rate limits. However, it does not explicitly state when not to use this tool instead of alternatives.

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

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

Annotations already indicate idempotent and read-only. Description adds caching behavior (5min-1h) and data derivation (no PII, just aggregates). No contradictions.

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

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

Front-loaded with core functionality, then use cases, then technical details. Every sentence adds value, 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?

With one simple parameter, complete annotations, and no output schema, the description covers purpose, usage, data source, and caching thoroughly. 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 covers the single parameter fully (enum, description). Description adds context about default and behavior differences between short/long windows, 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 it returns top tools, packs, and call volume over recent windows, with specific use cases. It distinguishes itself from siblings like discover_tools by focusing on trending data.

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

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

Three explicit use cases are provided, along with caching details. However, it lacks explicit when-not-to-use conditions or direct alternatives among siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so no safety concerns. The description adds behavioral details: the tool walks child markets, searches across events, groups them, and returns ranked opportunities with reasoning. No contradictions; full disclosure of process.

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

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

The description is well-structured with a clear main purpose followed by mode breakdowns. While slightly verbose, every sentence adds necessary detail. No redundant information.

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

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

Given the tool's complexity (two modes, cross-event search) and no output schema, the description adequately covers return format (ranked opportunities with direction and reasoning), key logic (monotonicity), and mode differences. Complete and 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?

Both parameters are documented in schema with descriptions. The description enhances this by explaining the purpose of each parameter (event vs topic mode) and provides examples, adding significant value beyond the schema.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations. It distinguishes two modes with specific usage scenarios, making it distinct from sibling tools like polymarket_edges.

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

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

Explicitly describes TWO MODES (event and topic) and provides concrete examples of when to use each, including the cross-event mode for cases where single-event mode fails (e.g., separate events for different cutoffs). This gives clear guidance on tool selection.

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

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

Description goes beyond annotations by detailing multi-step process (scan, group, fetch, compute, rank), external data sources (FRED, coinpaprika), and version scope (V1). Annotations already safe, but description provides operational 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?

Single paragraph front-loaded with purpose, then process, then use case. Efficient but not maximally concise; minor redundancy exists. Scores high but not perfect.

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?

Description adequately covers what, how, and output format (ranked list with direction). No output schema but description suffices. Missing details like rate limits or error handling, but overall sufficient for a read-only 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?

All three parameters have schema descriptions with defaults and constraints. Tool description merely restates or paraphrases these without adding new semantic context. Baseline 3 is appropriate given high 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?

Description clearly states the specific action: scan top Polymarket markets, compute model-based edges, and return top opportunities ranked by edge. Distinguishes from siblings like polymarket_arbitrage and bet_research by targeting the 'what should I bet on today' question.

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

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

Description explicitly states the tool is for discovering opportunities without manual browsing, implying usage context. Alternative tools exist but no explicit when-not-to-use guidance, though the scope 'crypto-price bets' narrows applicability.

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

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

Annotations readOnlyHint, openWorldHint, etc., are consistent. The description adds behavioral detail: it is a read-only calculation dependent on live venue prices, uses pre-mapped topics or explicit identifiers, and returns leg-by-leg prices and spreads.

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, starting with the core purpose, then explaining the significance of the spread, followed by two clear modes, and ending with return values. Every sentence adds value.

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

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

Despite no output schema, the description fully explains returns (leg-by-leg prices and spread) and covers the tool's complexity—two modes, mapping logic, and the arbitrage context. No gaps for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds context on the two modes and explains how parameters relate (e.g., 'Overrides the topic-mapped ... side'), enhancing understanding beyond the schema alone.

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

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

The description clearly defines the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It explains the arbitrage signal and two usage modes, effectively distinguishing it from sibling tools like polymarket_arbitrage.

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 outlines two modes (topic and explicit) but does not explicitly state when to use this tool versus alternatives like bet_research or polymarket_arbitrage. No guidance on when not to use it is provided.

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

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

Since no annotations are provided, the description bears full responsibility. It explains the core behavior: retrieving by key vs. listing all when key is omitted. However, it does not mention what happens if the key does not exist, or any error conditions.

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 main action, and avoids unnecessary details. Every word contributes meaning.

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

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

Given the tool's low complexity (one optional parameter, no output schema), the description is nearly complete. It could mention what format the returned memories take, but the omission is minor.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that omitting the key lists all memories, which is not explicit in the schema. 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 uses specific verbs ('retrieve', 'list') and clearly identifies the resource ('stored memory'). It distinguishes the two modes of operation (by key vs. all), which helps the agent understand the tool's scope.

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

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

The description explicitly states when to use this tool ('to retrieve context you saved earlier'), but does not contrast with alternatives like 'forget' or 'remember'. It omits explicit 'when not to use' guidance, though the context is clear.

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

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

No annotations provided, so description carries burden. Discloses parallel fan-out to SEC EDGAR, GDELT, USPTO, and return format (structured changes, count, URIs). Does not cover rate limits or auth, but sufficient for behavior understanding.

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

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

Four sentences front-load purpose, then detail parameters and output. No wasted words. Efficient and well-structured.

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

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

Given complexity (parallel sources, multiple data types) and no output schema, description fully covers purpose, input, behavior, and output shape. Agent can confidently invoke 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 significant value: for 'since' provides examples and typical monitoring suggestion; for 'value' explains ticker or CIK; for 'type' notes only 'company' supported. Exceeds baseline.

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

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

Clearly states verb and resource: 'What's new about an entity since a given point in time.' Specifies entity type 'company' and fan-out to multiple sources, distinguishing it from sibling tools like entity_profile.

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

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

Explicitly states when to use: 'Use for brief me on what happened with X or change-monitoring workflows.' Does not explicitly state when not to use or mention alternatives, 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?

No annotations provided, so description carries full burden. It discloses persistence differences: 'Authenticated users get persistent memory; anonymous sessions last 24 hours.' However, it doesn't mention side effects (e.g., overwriting existing keys) or idempotency, which would add value. With no annotations, this is adequate but not exhaustive.

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

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

Two sentences, no fluff. First sentence states core purpose, second gives use cases and behavioral notes. Each sentence adds unique value.

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

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

Given the tool's simplicity (2 string params, no output schema), the description fully covers purpose, usage, and key behavioral aspects. No gaps remain.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds usage examples ('subject_property', 'target_ticker') that are not in schema, providing extra context. However, the schema already describes key and value adequately, so the description adds moderate 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 'Store a key-value pair in your session memory' with specific verb 'store' and resource 'session memory'. It distinguishes from sibling tools like 'recall' (retrieval) and 'forget' (deletion) by focusing on writing to memory.

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

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

The description explains when to use this tool: 'save intermediate findings, user preferences, or context across tool calls'. It implicitly contrasts with 'recall' (retrieval) and 'forget' (deletion) as siblings. No explicit exclusions, but the examples provide 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?

With no annotations, description carries full burden. Discloses accepted input formats (ticker, CIK, name) and output fields (ticker, CIK, name, URIs). Does not mention edge cases like not-found or concurrency, but adequate for a simple resolution tool.

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

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

Four sentences, front-loads purpose, no fluff. Every sentence adds information: purpose, input specifics, output, and efficiency benefit. Perfectly concise.

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

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

No output schema, but description lists return fields. Covers inputs and output adequately. Missing error handling or limitations (e.g., rate limits), but for a simple tool it's nearly 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. Description adds context: explains both parameters in plain language, provides examples ('AAPL', '0000320193', 'Apple'), and notes versioning (v1 only supports company). Adds value beyond schema.

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

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

Description clearly states verb 'resolve' and resource 'entity to canonical IDs', specifies it's a single call replacing multiple lookups, and provides concrete examples (ticker, CIK, name). Differentiates from siblings by declaring it's the only entity resolution 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 'in a single call' and 'replaces 2–3 lookup calls', implying efficiency use case. Notes v1 only supports 'company', scoping usage. No explicit when-not-to-use, but sibling list shows no overlap, so it's 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?

Description adds behavioral details beyond annotations: it probes each entity with ai_visibility_check, ranks by score, and treats first entity as subject for narrative. Context signals (readOnlyHint, openWorldHint, etc.) are consistent and description provides extra context.

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

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

Two concise sentences plus a brief use-case note. No redundant information, well-structured and front-loaded with core 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, description clearly indicates return format (ranked list with score, confidence, signal density per entity). Given 4 parameters fully described, this is complete and sufficient for agent invocation.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: explains entities first entry as subject, clarifies models optional and _apiKey conditional, and context as shared disambiguator. This goes beyond schema descriptions.

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

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

Description explicitly states it compares AI visibility across entities, ranks by score, and surfaces most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the use case of competitive AI-marketing audits.

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

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

Description clearly mentions it is useful for competitive AI-marketing audits and explains the workflow. It implies single-entity checks should use ai_visibility_check, but lacks explicit when-not-to-use or alternative 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?

Describes return verdicts, extracted form, actual value with citation, and percent delta. Discloses sources (SEC EDGAR + XBRL) and scope. With no annotations, this provides substantial behavioral context.

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

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

Concise one-paragraph description with front-loaded purpose, followed by scope, returns, and benefit. Every sentence adds value with no redundancy.

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

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

Covers purpose, domain, source, return values, and efficiency advantage. Missing potential limitations (e.g., unsupported claim types or error handling), but sufficient for a simple single-param 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 a description, but the tool description adds valuable context about claim format and supported types (e.g., examples of financial claims).

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

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

Clearly states the tool fact-checks natural-language claims against authoritative sources, specifically company-financial claims for public US companies. Distinguishes from siblings like ask_pipeworx or resolve_entity which are generic.

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 describes when to use (replaces 4-6 sequential agent calls) and the supported claim domain. Does not provide explicit exclusions or alternatives, 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.