Datos Cl

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

Annotations already indicate safe, idempotent read operation. Description adds details about BYO key for Anthropic, payment responsibility, and return format (score, confidence, signals, raw_response). This provides useful 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?

Four sentences, front-loaded with main action, no redundant information. Each sentence earns its place, making it easy to parse quickly.

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

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

Given the tool's complexity and lack of output schema, the description covers purpose, model options, key requirements, and return structure. Could include more on scoring methodology, but current level is sufficient for competent use.

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

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

Schema coverage is 100%, so all parameters are described. The description adds extra context: default model (Workers AI Llama-3.3-70b), that Anthropic requires a key, and that the key is passed directly. 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 probes LLMs for knowledge about a business/brand/product/topic and scores visibility. It distinguishes from sibling tools like entity_profile or compare_entities by focusing specifically on AI visibility across models.

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

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

The description mentions use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It implies when to use but does not explicitly exclude alternatives or state when not to use, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the tool's safety profile is clear. The description adds behavioral context: it routes questions to 2,789 tools across 604 sources, fills arguments, and returns structured answers with stable citation URIs. This goes beyond annotations.

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

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

The description is well-structured, starting with the important caveat to prefer over web search, then listing domains, and ending with examples. Every sentence is informative, though it is somewhat long. It's concise enough given the breadth of the tool.

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

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

Given the tool's complexity (routing to many sources) and the annotations covering safety, the description is sufficient. It explains the routing mechanism and return format (structured answer with URIs). No output schema exists, so the description compensates adequately.

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

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

The input schema has one parameter 'question' with a clear description. Schema coverage is 100%, so the baseline is 3. The description adds value by explaining what kind of questions are appropriate and providing examples, which helps the agent formulate good queries.

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: answering factual questions about structured data from authoritative sources. It distinguishes itself from web search by saying 'PREFER OVER WEB SEARCH' and gives concrete examples of domains and queries, making the purpose very 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 provides clear guidance on when to use this tool versus web search, listing specific types of queries (SEC filings, FDA data, etc.) and even giving example phrasings ('what is', 'look up', 'find'). It also implies when not to use (if the query is not about authoritative structured 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 already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: it resolves market, classifies bets, fans out to relevant packs, and returns an evidence packet plus market-vs-model comparison. It also explains the depth parameter (quick vs thorough) and include_raw parameter (summarized vs full payloads) beyond the schema, 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?

The description is a single paragraph with 5 sentences, front-loading the purpose and then providing necessary detail. Each sentence adds value: purpose, input variants, internal process, output, and use cases. No fluff or repetition. Well-structured and appropriately concise for a complex tool.

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

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

Given the tool's complexity (multiple input types, parameter options, and output formats), the description covers all key aspects: what it does, how to use it, what it returns (evidence packet and comparison), and why parameters matter. No output schema exists, but the description sufficiently explains the output. Annotations cover safety. The description is complete for an AI agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. However, the description enriches parameter understanding: it explains the market parameter accepts slug, URL, or question text, aligns with schema but adds context. It clarifies depth defaulting to thorough and the trade-off between quick (2-3 sources) and thorough (full fan-out). It also explains why include_raw defaults false to keep responses small, adding practical guidance.

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 researches Polymarket bets using Pipeworx data, with specific verbs like 'Research a Polymarket bet' and 'resolve the market, classifies the bet.' It distinguishes itself from sibling tools by emphasizing it is the core demo product that handles fan-out across data packs, which differs from tools like polymarket_edges or 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 explicitly lists use cases: 'Use for "should I bet on X?", "what does the data say about this Polymarket market?", or "is there edge in this bet?"' It implies when to use but does not directly exclude alternative tools. However, context signals show many siblings, and the description positions the tool as the primary research tool, providing adequate 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, destructiveHint=false, idempotentHint=true. Description adds behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs) and return format (paired data + pipeworx:// citation URIs). No contradiction.

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

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

Five sentences, front-loaded with purpose, no redundant 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?

Despite no output schema, description mentions return format (paired data + citation URIs). Complex tool with clear usage and data sources; slight gap in explaining edge cases like invalid tickers or drug names.

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

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

Schema coverage is 100% and description adds meaning beyond schema by explaining what data each type pulls (e.g., revenue, net income for companies; adverse-event counts for drugs) and providing example values like 'AAPL', 'ozempic'.

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 compares 2–5 companies or drugs side by side, with specific use cases like 'compare X and Y', 'X vs Y'. It distinguishes from sibling tools such as entity_profile which handles single entities.

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

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

Explicitly states when to use (comparison questions, requesting tables/rankings). Implies alternative is multiple sequential calls (replaces 8–15 agent calls). Missing 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description doesn't need to repeat safety. It adds that the tool returns top-N most relevant tools with names and descriptions, providing clear 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?

The description is front-loaded with purpose and includes examples and usage guidance. While it is a bit long, every sentence earns its place. It could be slightly more concise, but it remains clear and informative.

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

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

Given the tool's simplicity (2 params, no output schema), the description fully explains what it does, when to use it, and what it returns. It provides sufficient context for an agent to decide whether to call this tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds example queries (e.g., 'analyze housing market trends') but does not add significant new meaning beyond what the schema already provides. The parameter descriptions in the schema are already clear.

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 'Find tools by describing the data or task' and provides numerous examples (SEC filings, FDA drugs, etc.). It clearly distinguishes itself from siblings by positioning as a discovery meta-tool, instructing to call it FIRST to see the option set.

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 for' and 'Call this FIRST' when many tools are available. It provides clear context but does not explicitly state when not to use, though it's 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 declare readOnly, openWorld, idempotent, and non-destructive, so the description doesn't need to repeat safety. It adds value by disclosing that results include 'pipeworx:// citation URIs' and lists the data sources (SEC EDGAR, SEC XBRL, USPTO, news, GLEIF). This provides context about behavioral scope (aggregated, multi-source) without contradicting annotations.

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

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

The description is a single paragraph of three sentences, each earning its place: purpose/usage triggers, return contents, and parameter constraints. No wasted words, front-loaded with the core action ('Get everything about a company in one call'), and structured for quick scanning.

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

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

Given the tool's complexity (aggregates across SEC, USPTO, news, GLEIF) and the absence of an output schema, the description covers the main return elements and input constraints. It could be more complete by mentioning any limits (e.g., max results per category) or pagination, but for an initial invocation decision it is sufficient. The provided information allows an agent to understand the scope and decide if this tool fits the user's need.

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 both parameters with 100% description coverage. The description enhances schema by clarifying that the 'type' enum currently only supports 'company' (with future plans mentioned), and that 'value' accepts tickers or zero-padded CIKs, explicitly noting that names are unsupported and directing to 'resolve_entity' as a prerequisite. This eliminates ambiguity.

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 begins with a clear verb-resource pair: 'Get everything about a company in one call.' It then lists specific data types returned (SEC filings, fundamentals, patents, news, LEI) and provides example user queries that map directly to the tool's use. This purpose is distinct from sibling tools like 'resolve_entity' (name-to-identifier) and 'compare_entities' (comparison).

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

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

Explicitly tells when to use: user asks for company profile (multiple example phrases). Also tells when NOT to use: names are not supported, advising to 'use resolve_entity first if you only have a name.' Additionally, it positions the tool as an alternative to calling 10+ pack tools, giving clear situational guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds 'Delete' but no further behavioral context (e.g., behavior on missing key, permanence). Adequate given 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?

Two concise sentences, direct and clear, with no unnecessary words. Front-loaded with action and usage guidance.

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?

Simple tool with one parameter and no output schema. Description covers purpose and usage but lacks expected return behavior or error handling. Acceptable for low 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% with 'Memory key to delete.' Description says 'by key' but adds no new meaning. Baseline 3 as schema 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 clearly states 'Delete a previously stored memory by key,' specifying the action and resource. It distinguishes from siblings by mentioning 'Pair with remember and recall,' but does not explicitly differentiate use cases.

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 conditions for use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with related tools. Lacks explicit when-not-to-use or alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: fetches the page, extracts title/description/key links, emits markdown format, and outputs a text blob. This is consistent and informative 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 paragraphs: first sentence clearly states purpose, second paragraph adds detail and use cases. It is front-loaded and every sentence serves a purpose, though could be slightly more compact.

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 explains the output as 'a single text blob ready to drop at site-root/llms.txt', which suffices for a simple generation tool. The description is complete given the tool's simplicity and rich annotations.

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

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

Schema coverage is 100% with descriptions. The description does not add extra meaning beyond the schema; it repeats default values (max_links default 25) which are already in the schema. Thus baseline 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?

Clearly states the verb 'generate' and the specific resource 'llms.txt file', with context of AI crawler indexing. The description distinguishes the tool from siblings by its unique function of producing a standard llms.txt markdown, which is not evident in any sibling 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 lists three use cases: getting a client's site indexed, drafting for own project, auditing competitor sites. While it provides when to use, it does not mention when not to use or alternatives, hence a 4.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, making the safe nature clear. The description adds no extra behavioral context but does not contradict.

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 short (two words) but lacks meaningful content. This is under-specification rather than efficient conciseness.

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 an output schema, the description provides no context about the purpose, filtering, or expected results. It is insufficient for a tool with three parameters and multiple siblings.

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 0%, and the description does not explain any of the three parameters (limit, offset, all_fields). The description fails to compensate for the missing schema descriptions.

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

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

The description 'Groups/categories.' is a tautology that does not specify any action or resource. It lacks a verb like 'list' or 'retrieve', making it unclear what the tool actually 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?

No guidance on when to use this tool versus sibling tools like group_show or tag_list. The description provides no context for selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no behavioral context beyond what annotations provide.

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

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

The description is only two words, which is under-specified rather than appropriately concise. It does not provide enough information to be useful.

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 low schema coverage and the presence of an output schema, the description should at least state that the tool retrieves details for a single group. It is incomplete and insufficient for an agent to correctly invoke the tool.

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

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

Schema description coverage is 0%, and the description does not explain the parameters (id, include_datasets). The examples in the schema offer some context, but the description fails to add 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?

The description 'Single group.' is vague and lacks a clear verb-resource relationship. It does not indicate that the tool retrieves or shows group details, and it does not distinguish from sibling tools like group_list.

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 is provided on when to use this tool versus alternatives (e.g., group_list, organization_show). There are no usage conditions or exclusions mentioned.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false. The description adds only the domain 'Publishing orgs,' but no behavioral details like pagination, ordering, or result 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?

The description is extremely short (2 words) but it is under-specified rather than concise. It omits essential information and does not earn its place as a meaningful description.

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 presence of 3 undocumented parameters and sibling tools requiring differentiation, the description is grossly incomplete. It fails to provide a complete understanding of the tool's functionality, inputs, or outputs.

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 0%, yet the description fails to explain the purpose or usage of the three parameters (limit, offset, all_fields). No compensation for missing schema details.

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 'Publishing orgs.' is a phrase without a verb, making it unclear what action the tool performs (e.g., list, show, manage). It does not distinguish from sibling tools like organization_show or group_list.

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 such as organization_show or package_list. The description provides no context for appropriate usage scenarios.

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 idempotentHint. The description adds no behavioral context beyond what is already known, failing to disclose return behavior or 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?

Extremely brief, but at the cost of clarity. The single sentence does not earn its place as it provides insufficient 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 having an output schema and two parameters, the description is wholly inadequate. It does not explain tool function, parameter effects, or return structure.

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 0% and the description does not explain the two parameters (id, include_datasets) or their roles. No meaning is added 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 'Single org.' is a tautology of the tool name. It does not specify what action is performed or what resource is involved, failing to distinguish from siblings like organization_list.

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 such as organization_list or package_show. No usage context is provided.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which adequately convey the tool's safe and non-destructive behavior. The description adds no new behavioral traits beyond stating it lists names, so it meets the baseline expectation but does not exceed it.

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 (three words), which is efficient but arguably too minimal. It front-loads the purpose, but a more informative sentence (e.g., including 'with optional pagination') would be equally concise and more useful without adding bulk.

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 (not shown) and sibling tools with more descriptive definitions, the description leaves ambiguity about the return format, pagination details, and whether it lists all datasets or only accessible ones. The 0% schema description coverage amplifies the need for the description to compensate, which it does not.

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

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

The input schema has two parameters (limit and offset) with no descriptions (0% coverage), and the description does not explain their purpose or how they affect results. Without the description, an agent would have to infer from examples in the schema, which is insufficient for correct usage.

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 'List dataset names' clearly identifies the action (list) and resource (dataset names), and in the context of siblings like package_search and package_show, it implies a simple enumeration without filtering. However, it does not specify whether it lists all datasets or paginated results, nor does it distinguish from package_search which also lists datasets but with search criteria.

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 like package_search (which supports filtering) or package_show (which returns details). The description does not mention any prerequisites, limitations, or context where this tool is preferred.

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 no further behavioral context such as rate limits, response size, or ordering of results.

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 at four words, with no unnecessary information. However, it could be expanded slightly to improve clarity without losing conciseness.

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 a faceted search tool with 6 parameters and no parameter descriptions, the description is inadequate. An output schema exists, so return values need not be explained, but input guidance is missing.

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

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

With 0% schema description coverage, the description should explain parameter meanings. It only says 'full-text + faceted search' without detailing 'q', 'fq', 'rows', etc. The provided examples in the schema partially compensate but are not part of the description.

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

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

The description 'Full-text + faceted search' clearly indicates the tool performs search with full-text and faceting capabilities. It distinguishes from siblings like package_list and package_show by specifying search functionality, but does not explicitly differentiate from other search-like 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 no guidance on when to use this tool versus alternatives (e.g., package_list, package_show). It does not mention any scenarios, prerequisites, or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc., so the description adds no extra behavioral context beyond stating it deals with a single dataset. No mention of response structure or limitations.

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?

While extremely short, the description sacrifices usefulness for brevity. It does not provide enough information to justify its conciseness.

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 presence of many sibling tools and an output schema, the description is incomplete. It does not clarify what the output contains or how it differs from related tools.

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

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

Schema coverage is 0% for the 'id' parameter. The description does not explain what the ID represents or its format, even though an example is provided in the schema.

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

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

Description 'Single dataset.' is too vague; it lacks a verb (e.g., retrieve, show) and fails to differentiate from sibling tools like package_list or package_search, which also deal with 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?

No guidance is provided on when to use this tool versus alternatives like package_search or package_list. The description does not mention context such as retrieving details by ID.

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 it's free, rate-limited to 5 per identifier per day, and does not count against tool-call quota. It also explains how feedback is processed ('team reads digests daily,' 'signal directly affects roadmap'), adding behavioral context beyond the annotations.

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

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

The description is concise (91 words) and well-structured: it starts with the core action, then usage guidelines, then behavioral notes. 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's moderate complexity (3 parameters, 1 enum, nested object) and no output schema, the description covers all necessary aspects: what it does, when to use it, how to format feedback, and constraints. It is fully adequate 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%, and the description adds meaning beyond the schema: it elaborates on the type enum values and provides detailed guidance on the message field (specificity, length). The context object's purpose is also clarified.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies four distinct categories (bug, feature, data_gap, praise) and differentiates from sibling tools by focusing on Pipeworx tools/packs rather than end-user prompts.

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 when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also includes what not to do ('don't paste the end-user's prompt') and notes on rate limits and quota.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: 'derived from CF analytics-engine', 'no PII', 'cached 5min-1h depending on window', and 'self-aggregating signal'. 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?

Five sentences, front-loaded with purpose, followed by bullet-like use cases, then data source and caching notes. Every sentence adds value; no redundancy or filler.

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 (1 param, no output schema, strong annotations), the description fully covers purpose, usage, parameter nuance, and behavioral traits, leaving no gaps for an agent to misinterpret.

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

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

Schema already covers 100% of the single parameter with enum and description. The description adds extra context: notes that '24h' is default, and explains that shorter windows surface hot trends while longer windows show steady-state demand, surpassing the schema's simple listing.

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, top packs, and total call volume' over a configurable window, using specific verbs and resource. It distinguishes itself from siblings like 'discover_tools' or 'entity_profile' by focusing on trending/popularity signals from other AI agents.

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 concrete use cases: (1) discovering hot data sources, (2) confirming popular tools, (3) seeing alignment with agent needs. It also contrasts short vs long windows. However, it does not explicitly mention when not to use it or name 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?

Annotations already indicate non-destructive, read-only behavior. The description adds meaningful context by detailing how the tool checks monotonicity violations, walks child markets, searches across events, and returns ranked opportunities. This goes beyond annotations, earning a score of 4.

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 (around 100 words) and well-structured, with clear front-loading of purpose followed by detailed mode explanations. Every sentence adds value without redundancy, achieving the highest score.

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 return value ('ranked opportunities with suggested trade direction + reasoning'). It comprehensively covers input modes, behavior, and output, leaving no critical 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 description coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining the two modes ('event' and 'topic') and providing examples, making the parameters more understandable. Hence, a score of 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 tool finds arbitrage opportunities via monotonicity violations on Polymarket. It provides specific verb and resource, but does not differentiate from sibling tools like polymarket_edges, so it meets the criteria for a score of 4.

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 two modes with clear context for when to use each, but it does not compare this tool to sibling tools (e.g., polymarket_edges, polymarket_kalshi_spread) or state when not to use it. Usage guidelines are implied rather than explicit, resulting in a score of 3.

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 the internal process: scans top markets, groups by asset, fetches price history ONCE, computes model probability, ranks by |edge|, and returns top N with suggested direction. Annotations already indicate read-only, idempotent, and non-destructive, and the description adds valuable detail without contradiction.

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

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

The description is well-structured, starting with the main purpose, then the method, then output. Every sentence adds value, and there is no redundancy. It is appropriately sized for the complexity of the tool.

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

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

Despite no output schema, the description clearly states the output: top N ranked by edge magnitude with suggested trade direction. It covers data sources, algorithm, and filtering parameters. For a discovery tool with simple output, this is sufficient and 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?

All parameters have schema descriptions (100% coverage). The description enriches them with defaults, constraints (max 25 for limit), and rationale (slippage explanation). While schema already covers basics, the description adds context that helps agents decide parameter values.

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 scans high-volume Polymarket markets, identifies where Pipeworx data disagrees with market price, and returns top N edges with suggested trade direction. It specifies it covers crypto-price bets using a lognormal model and live price data, distinguishing it from siblings 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 explicitly frames the tool for the 'what should I bet on today' question, avoiding manual browsing. While it doesn't list when not to use it, the context implies it's for opportunity discovery, and sibling tools suggest alternatives for arbitrage or spread comparisons.

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

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

Annotations declare readOnly, idempotent, openWorld, non-destructive. Description adds context: typical price difference range (2-25pp), two operational modes, and return structure (leg-by-leg prices, spread). No contradictions.

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

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

Well-structured and front-loaded with purpose. Slightly verbose but every sentence adds value. Could be tightened slightly.

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 return values (leg-by-leg prices, spreads) and covers both modes completely. Enough 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% with descriptions for all 3 parameters. Description adds value by explaining modes, override behavior, and return format, going beyond schema details.

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 computes cross-venue spread between Kalshi and Polymarket for the same question, explains two modes (topic shortcuts and explicit tickers), and distinguishes from siblings like polymarket_arbitrage by focusing on spread calculation.

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

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

Describes when to use topic mode (pre-mapped macros) vs explicit mode (custom pairings), implies alternatives via sibling tools, and mentions real arb signal. Could explicitly compare to siblings for 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 mark it as read-only and idempotent. The description adds behavioral context beyond annotations: scoping to the agent's identifier and the behavior of omitting the key argument to list all keys.

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 with no redundancy. Each sentence provides essential information: core function, usage context, and pairing instructions. It is 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?

For a simple tool with one optional parameter and comprehensive annotations, the description covers all necessary context: return behavior, scoping, pairing with sibling tools, and usage examples. No gaps remain.

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

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

Schema coverage is 100%, but the description adds meaning with concrete examples (e.g., 'user's target ticker, an address') and explains the effect of omitting the key. This enriches 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 the tool retrieves a saved value or lists all keys, with specific verb ('retrieve', 'list') and resource ('value previously saved', 'all saved keys'). It distinguishes from siblings like 'remember' 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?

The description explains when to use the tool ('to look up context the agent stored earlier') and includes examples. It doesn't explicitly state when not to use it, but the pairing with 'remember' and 'forget' implies the usage boundaries.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc. The description adds value by explaining the parallel fan-out to SEC EDGAR, GDELT, and USPTO, and details the return structure (structured changes + total_changes + citation URIs). No contradictions with annotations.

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

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

The description is a single dense paragraph. It is efficient but could benefit from slight structuring (e.g., bullet points or separate sections). Every sentence adds value, so no 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 moderate complexity (3 params, no output schema), the description adequately covers what the tool returns (structured changes, count, URIs). It does not explain potential limitations or rate limits, but for a read-only tool with annotations, 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?

Input schema has 100% coverage with descriptions. The description adds practical guidance, e.g., that 'since' accepts ISO or relative shorthand and recommends '30d' or '1m' for monitoring, and that 'value' can be ticker or CIK. This goes 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: 'What's new with a company in the last N days/months?' and provides concrete user query examples. It distinguishes itself from siblings like 'entity_profile' by specifying it focuses on recent changes across multiple data sources.

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 when to use the tool (e.g., 'what's happening with X?', 'any updates on Y?') and mentions the underlying data sources. However, it does not explicitly state when not to use it or point to alternative tools, so it's not a perfect 5.

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

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

Annotations already indicate readOnly and idempotent behavior, but the description adds no additional behavioral context such as pagination, ordering, or result scope. It does not contradict annotations but adds zero 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 only two words, which is insufficient rather than concise. It fails to provide the minimum 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 having an output schema and clear annotations, the description omits the core purpose and parameter usage. It is completely inadequate for a useful tool definition.

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

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

The input schema has 0% description coverage, and the description provides no explanation of the 'limit' and 'offset' parameters. The agent has no clue what these parameters control.

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 'Recent updates.' is a tautology that essentially restates the tool name without specifying what is updated. It fails to distinguish from sibling tools like 'recent_changes' or 'package_list'.

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 'package_search' or 'recent_changes'. There is no mention of context or exclusions.

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

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

Annotations provide idempotentHint=true and destructiveHint=false; the description adds persistence details (authenticated vs anonymous 24h) and scoping, 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?

Efficiently written in four sentences, front-loaded with purpose, no redundancy, each sentence adds distinct 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 simple tool (2 params, no output schema), the description covers purpose, usage, persistence, and sibling links, making it fully actionable.

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

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

Schema coverage is 100% with clear parameter descriptions; the description adds naming conventions like 'subject_property' which enriches 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 'Save data the agent will need to reuse later' and distinguishes it from sibling tools recall and forget, providing specific verb+resource with clear 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?

Explicitly states when to use ('when you discover something worth carrying forward') and pairs with recall and forget, offering clear context and 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 and idempotentHint true, so the description's role is to add behavioral context beyond these. It does so by specifying the output (IDs plus citation URIs) and the read-only nature ('Look up'), which aligns with annotations. It avoids 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 (5 sentences) and well-structured: purpose, usage guidance, examples, output description, usage order, and efficiency benefit. Every sentence adds value and is front-loaded, making it easy for an AI agent to quickly grasp the tool's function.

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 covers return values (IDs and citation URIs). It explains input parameters with examples, states when to use it (before other tools needing identifiers), and lists the ID systems. This provides sufficient context for an AI agent to use the tool effectively among many siblings.

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

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

With 100% schema description coverage, the schema already explains parameters well. The description adds value by providing concrete examples ('Apple' -> AAPL, 'Ozempic' -> RxCUI) and clarifying how the value parameter is interpreted (ticker, CIK, name for companies; brand/generic for drugs), which enriches meaning beyond the schema.

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

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

The description clearly defines the tool's purpose: looking up canonical identifiers for companies and drugs. It provides specific examples (Apple -> AAPL/CIK, Ozempic -> RxCUI) and distinguishes from siblings by stating it replaces 2-3 lookup calls, making it unique among tools like entity_profile or compare_entities.

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

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

The description explicitly instructs to use this tool 'BEFORE calling other tools that need official identifiers', providing strong contextual guidance. It also implies when not to use (when you already have the identifier) and suggests efficiency gains by replacing multiple calls, though it doesn't name specific 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?

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds no additional behavioral context (e.g., error cases, return format, authorization). It fails to add value beyond structured fields.

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?

While short, the description is under-specified rather than concise. It lacks necessary detail to be functional, making it inefficient for agent 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?

Despite having an output schema and sibling tools with similar patterns, the description omits return value information, scope, and operational context. It is incomplete for effective tool usage.

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

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

The input schema has a single required 'id' parameter with no description; schema description coverage is 0%. The description provides no meaning or constraints for the parameter, leaving the agent uninformed about what identifier to provide.

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 'Single resource' is vague and does not clearly state the action (e.g., fetch, retrieve, display) or differentiate from sibling tools like package_show or organization_show. It barely adds more than the tool name.

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 (e.g., other show tools or search tools). The description lacks context for appropriate invocation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructive effect. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks results, and returns scores, confidence, and signal density. No contradiction with annotations.

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

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

Two sentences that front-load the purpose and include a concrete example. No wasted 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?

The description explains what the tool does (probes, ranks, surfaces), what it returns (ranked list with score, confidence, signal density), and when to use it. With no output schema, this is sufficiently complete for a comparison tool with 4 parameters.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by noting that the first entity in 'entities' is treated as the 'subject' for narrative, and that 'context' disambiguates common names. This adds value beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. This is a specific verb+resource action that distinguishes it from the sibling ai_visibility_check.

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

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

The description provides a clear use case: 'competitive AI-marketing audits' with an example question. It implicitly suggests use when comparing multiple entities, but does not explicitly state when not to use it or name alternatives beyond mentioning ai_visibility_check as the probing mechanism.

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, openWorld, idempotent, and non-destructive behavior. The description adds no additional behavioral context (e.g., pagination, scope, or return format), failing to add 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 extremely concise but at the cost of informativeness. It consists of two words that add no new information beyond the tool name, exemplifying under-specification rather than effective conciseness.

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 presence of an output schema, the description does not need to explain return values, but it fails to mention filtering, pagination, or any operational details. The tool has 3 optional parameters with zero explanation, making it severely incomplete.

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 0%, and the description does not explain any of the three parameters (query, all_fields, vocabulary_id). The agent cannot infer their semantics from the description 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 'Tag list.' is essentially a tautology of the tool name, providing no verb or resource distinction. It does not differentiate from sibling list tools like group_list or package_list.

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 is provided on when to use this tool versus alternatives. With many sibling list tools, this omission forces the agent to guess 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, destructiveHint. Description adds behavioral details: returns a verdict, extracted structured form, actual value with pipeworx:// citation, and percent delta. Explains internal process (NL parsing → entity resolution → data lookup → numeric comparison) and scope (public US companies via EDGAR+XBRL). Exceeds transparency expected from annotations alone.

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 a single paragraph of 5 sentences, front-loaded with purpose and usage. Clear and concise. Could be slightly more structured (e.g., separate usage from return value), but 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 complexity (parsing, resolution, comparison), description covers purpose, domain, return values, and efficiency improvement. No output schema, so return detail is adequate. Could mention limitations (only US public companies, only financial claims) more explicitly, but 'v1 supports company-financial claims' implies it.

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

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

Only one parameter 'claim' with 100% schema coverage and description. Description adds natural-language examples and clarifies that the claim should be a factual statement. Schema already covers type and required, so the description provides helpful context but is not strictly necessary.

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 fact-checks natural-language claims against authoritative sources, specifies it supports company-financial claims via SEC EDGAR + XBRL, and distinguishes itself by replacing multiple sequential calls. Specific verb 'fact-check, verify, validate, confirm/refute' with resource 'authoritative sources' and examples.

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 'Use when an agent needs to check whether something a user said is true' with example queries. Implicitly limited to company-financial claims for v1, but does not explicitly state when not to use (e.g., non-financial claims). Could mention alternatives among siblings.

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