Comtrade

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

Discloses default model, API key requirement, and cost implication (BYO key). Annotations already indicate read-only, idempotent, non-destructive; description adds operational details.

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 four sentences, front-loaded with core function. 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?

No output schema, but description details return structure (per-model and combined). Also explains cost and usage. Thorough for its 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?

Adds context beyond schema: examples for entity, supported models list, explanation of _apiKey dependency, and purpose of context parameter. Schema coverage is 100%.

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

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

The description clearly states the tool probes LLMs for brand visibility and scores it 0-100. It distinguishes from siblings like scan_competitor_ai_presence by focusing on LLM knowledge scoring.

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?

Lists use cases (AI-marketing audits, pre-launch checks). Does not explicitly exclude scenarios or mention alternatives, but context is clear enough.

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 key behavioral traits: it picks the right tool, fills arguments, and returns results. It implies the tool may have broad capabilities but doesn't specify limitations or which data sources are available. No annotations are provided, so the description carries full burden, but it sufficiently sets expectations.

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 and front-loaded with the core purpose. It uses two clear sentences followed by examples. 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 simplicity (one required parameter, no output schema), the description is complete. It explains what the tool does, how to use it, and provides examples. No further details are necessary.

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

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

The description adds meaning beyond the input schema by explaining that the 'question' parameter should be in plain English and gives examples. Schema coverage is 100%, so the baseline is 3; the description adds extra value with usage 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?

The description clearly states the tool's purpose: 'Ask a question in plain English and get an answer from the best available data source.' It uses specific verbs ('ask', 'get') and describes the resource ('answer from best available data source'). It differentiates from sibling tools by highlighting its natural language interface and automatic tool selection, contrasting with the more specific sibling tools like comtrade_trade_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?

The description provides explicit guidance on when to use this tool: 'No need to browse tools or learn schemas — just describe what you need.' It implicitly suggests using other tools when you have a specific data source in mind, as this tool abstracts away tool selection. Examples illustrate appropriate use cases.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds behavioral details beyond annotations: it resolves markets, classifies bet types, fans out to relevant packs based on bet type, and returns an evidence packet with model comparison. 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 5 sentences, front-loaded with the main purpose. Each sentence adds value, though slightly verbose. It efficiently conveys the core functionality, usage examples, and benefits.

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

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

Without an output schema, the description explains return values: 'evidence packet plus a simple market-vs-model comparison'. It also describes the internal processing (classification, fan-out). This is sufficient for an agent to understand what the tool returns and how it works.

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 explaining the market parameter accepts slug, URL, or question text, and for depth it clarifies 'quick = 2-3 evidence sources, thorough = full fan-out. Default thorough.' This provides context beyond the enum values in the schema.

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

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

The description clearly states the tool researches Polymarket bets, specifying the verb 'Research', the resource 'Polymarket bet', and the action of pulling relevant Pipeworx data in one call. It distinguishes from siblings by focusing on Polymarket and aggregating multiple data packs, which is not done by other tools like ask_pipeworx.

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

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

The description provides explicit usage contexts: 'should I bet on X?', 'what does the data say about this Polymarket market?', 'is there edge in this bet?'. It implies the tool is best for bet research and states that agents using it convert better than discovering packs themselves. However, it does not explicitly exclude alternatives or specify when not to use it.

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

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

With no annotations, the description holds full burden. It discloses return format (paired data + resource URIs) and specific data fields per type. It does not mention side effects or auth, but these are less critical for a read-only-like comparison tool; inferred as non-destructive.

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

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

Two concise sentences, front-loaded with the core purpose. Every phrase adds information without redundancy or fluff.

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

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

Covers key aspects: purpose, input types, metrics, output format. While no output schema exists, the description sufficiently explains what is returned. Minor gap: could mention that the comparison result is a single response (implicit from 'one call').

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

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

Schema coverage is 100%, baseline 3. The description adds value beyond the schema: it explains the type enum with examples ('company', 'drug') and provides concrete examples for the values parameter (e.g., tickers, drug names).

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 compares 2-5 entities side by side, lists specific metrics for company and drug types, and distinguishes it from siblings by noting it replaces multiple 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?

Provides clear context on when to use (comparing 2-5 entities by type) and highlights efficiency benefit over sequential calls. Does not explicitly state when not to use or list alternatives, but the context is strong.

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

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

With no annotations, the description must disclose behavior. It states 'No API call needed', indicating fast, local retrieval. However, it doesn't specify what happens if the list is empty or if it returns all countries or only common ones.

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, no fluff. Front-loaded with purpose, then efficiency note.

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

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

The tool has no parameters and no output schema, but the description explains its static nature. For a simple reference list, this is adequate, though more detail on what 'common' means could help.

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 no parameters and 100% coverage, so baseline is 3. The description adds no parameter info, but none is needed.

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

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

The description clearly states the tool returns a reference list of common country ISO numeric codes for UN Comtrade queries. It distinguishes itself from data query tools like comtrade_trade_data by being a reference/list tool.

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

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

The description says 'Get a reference list' and 'No API call needed', implying it's a static lookup and not a live query. Sibling tools like comtrade_trade_data are for actual data, so this tool is for reference only.

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 correctly states the tool retrieves top commodities by trade value, implying a read-only operation. However, it doesn't disclose behavior like default limit (20), sorting direction, or whether results are aggregated. With zero annotations, the description should provide more 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?

Two short sentences that are front-loaded with the core purpose. 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?

Given the complexity (5 params, no output schema), the description is somewhat minimal. It explains the output conceptually (which product categories dominate) but doesn't specify the return format (e.g., list of HS codes with values). With no output schema, the description should provide more detail on what the agent will receive. However, the tool is relatively straightforward, so a 3 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?

Schema description coverage is 100%, so the schema already documents all parameters. The description adds meaning by explaining the tool's purpose (top commodities by trade value), which implies the limit parameter controls the number of results. However, it doesn't elaborate on parameter relationships or constraints beyond what the schema provides. Baseline 3 plus some added 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 clearly states the tool gets 'top traded commodities between two countries by trade value' and explains what it shows. It uses specific verbs and resources, and distinguishes itself from siblings like comtrade_trade_data (which likely provides detailed data) and comtrade_top_partners (which focuses on partners). However, it could more explicitly differentiate from comtrade_top_partners.

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 when analyzing bilateral trade composition, but provides no explicit guidance on when to use this vs. comtrade_trade_data or comtrade_top_partners. No exclusions or alternatives are mentioned. The context signals indicate sibling tools exist, but the description doesn't leverage this to guide 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?

No annotations provided, so description carries full burden. States it returns top partners by trade value, which implies a sorted result. Does not disclose sorting order, pagination, or data freshness. Adequate but not thorough.

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, concise and front-loaded with purpose. Could be slightly more structured, 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 5 parameters, no output schema, and no annotations, the description is adequate but lacks details on output format, sorting, or edge cases. Does not explain default limit behavior.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add additional parameter meaning beyond schema descriptions.

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

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

Clearly states it gets top trading partners for a country by trade value. Distinguishes from sibling tools like comtrade_trade_data (broader) and comtrade_top_commodities (different focus), but does not explicitly differentiate.

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?

Implied usage: understanding main trade relationships. No explicit when-to-use or when-not-to-use guidance, nor comparison with 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?

No annotations provided, so description carries full burden. It describes the tool as a data retrieval operation but does not mention any constraints like rate limits, data freshness, or whether it returns raw or aggregated data.

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, concise and front-loaded with the core purpose. Every sentence adds value, but could include more guidance on when to use it without being verbose.

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

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

Given no output schema, the description partially compensates by listing return fields (trade value, quantity, partner, commodity). However, it does not describe pagination, error handling, or data limits. Adequate but not thorough.

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

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

Input schema covers 100% of parameters with descriptions. The tool description adds minimal extra meaning beyond the schema, but it mentions the default for flow ('M,X') which is not in the schema. Baseline 3, plus 1 for added default value info.

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 bilateral trade data between two countries from the UN Comtrade database, specifying return fields like trade value, quantity, partner, and commodity. However, it does not differentiate from siblings like comtrade_top_commodities or comtrade_top_partners.

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 trade data between two countries, but does not explicitly state when to use this tool vs. alternatives such as comtrade_top_commodities or comtrade_top_partners. No exclusions or prerequisites are 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?

No annotations are provided, so the description carries the full burden. It describes the tool as a search/catalog discovery tool, which implies it is read-only and non-destructive. However, it does not disclose any behavioral traits such as whether it uses vector search, caching, or rate limits. A score of 3 is appropriate because the description covers basic behavior but lacks depth.

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, consisting of three sentences with no wasted words. The key instructions are front-loaded: the first sentence states the purpose, the second indicates the return value, and the third gives a clear when-to-call directive.

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 parameters, no output schema, no nested objects), the description is nearly complete. It explains what the tool does, what it returns, and when to use it. A minor gap is that it doesn't describe the format of the returned results (e.g., list of tool names and descriptions), but the description does state 'Returns the most relevant tools with names and descriptions,' which 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 baseline is 3. The description adds value by explaining that the query parameter should be a 'natural language description' and gives examples, which goes beyond the schema's generic description. The limit parameter is also mentioned with default and max values in the schema, but the description does not add extra semantics beyond that. Overall, the description enhances understanding of the query parameter, warranting 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 states a specific verb-resource combination ('Search the Pipeworx tool catalog') and clearly distinguishes the tool from siblings by indicating it is to be called 'FIRST' when the agent has 500+ tools, which differentiates it from other tools that perform specific data retrieval tasks.

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 the agent to call this tool first when many tools are available, and provides clear context ('Call this FIRST when you have 500+ tools available and need to find the right ones for your task'). This gives definitive when-to-use guidance.

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

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

With no annotations, the description fully covers behavioral aspects: it returns pipeworx:// citation URIs, lists data sources, states only company is supported, and mentions it is a read operation replacing many calls.

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

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

Description is concise (4 sentences) with no wasted words. It front-loads the main purpose and includes all necessary details in a structured, easy-to-read format.

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 annotations or output schema, the description is complete: it explains what the tool does, what data it returns, parameter usage, and when to avoid it. An agent can fully understand how to use 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?

Description adds significant meaning beyond the schema: for 'value' it specifies ticker or CIK and says names not supported (use resolve_entity). For 'type', it repeats enum but adds future plans. Schema coverage is 100% but description enhances usability.

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 full entity profile from multiple Pipeworx packs in one call, listing specific data sources (SEC, XBRL, USPTO, GDELT, GLEIF). It distinguishes itself from siblings like resolve_entity 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?

The description explicitly advises when not to use it: for federal contracts, use usa_recipient_profile. It also implies use for comprehensive entity data and notes that name resolution requires 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 provided, so description carries burden. It discloses deletion action but omits details like reversibility, permissions needed, or side effects. Adequate but minimal.

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 short sentence with no fluff. Could be slightly more informative, but very 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?

Simple tool with 1 param, no output schema, no nested objects. Description covers the basic purpose and parameter. Could add info about case sensitivity or persistence, but adequate for a straightforward deletion.

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 schema already describes key as 'Memory key to delete'. Description adds no extra meaning beyond 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?

Description clearly states the action (delete), resource (stored memory), and identifier (key). Distinguishes 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?

Description implies use when you need to delete a memory by key, but no explicit guidance on when to use alternatives or when not to use this tool. Siblings provide context, but description doesn't leverage it.

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

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

The description explains the tool fetches a page and extracts metadata, which aligns with the readOnlyHint and idempotentHint annotations. It adds behavioral details beyond annotations (e.g., output format) 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 three sentences, each essential: purpose, process, and use cases. No wasted words, effectively front-loaded.

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

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

Given the tool simplicity (2 params, no output schema), the description covers purpose, process, output format, and use cases. It is complete for the agent to understand 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 coverage is 100% so baseline is 3. The description provides context for the url parameter but doesn't add significant meaning beyond the schema for max_links. Minimal extra value.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, explaining the process and output. It distinguishes itself from other tools on the server as unique in function.

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 (client site indexing, own project, competitor audit) but does not explicitly state when not to use it or name alternative tools. The context is clear enough 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?

Without annotations, the description carries the full burden. It discloses rate limits (5 messages per identifier per day) and states 'Free'. It also warns about not including prompt verbatim. However, it does not describe what happens after sending (e.g., whether feedback is reviewed, confirmation, or any side effects), leaving behavioral gaps.

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 very concise: three sentences covering purpose, usage guidelines, and constraints. No redundant information. Every 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?

The description covers the essential context for a feedback tool: what it does, how to structure feedback, and rate limits. However, it lacks mention of the tool's output (e.g., acknowledgment) and error behaviors, which could be helpful for an agent. Given simplicity, it is largely complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by instructing to 'Describe what you tried in terms of Pipeworx tools/data', which provides concrete guidance for the 'message' parameter. This goes beyond the schema's basic description.

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

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

The description clearly states the action ('Send feedback') and specifies the resource ('Pipeworx team'). It enumerates specific use cases (bug reports, feature requests, missing data, praise) and differentiates from sibling tools like ask_pipeworx by focusing on feedback rather than queries.

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

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

The description explicitly states when to use the tool (for feedback types) and includes a clear do-not (avoid including the end-user's prompt verbatim). It also mentions rate limiting. However, it does not explicitly contrast with alternatives (e.g., 'for questions, use ask_pipeworx'), which would strengthen 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 show readOnly, idempotent, non-destructive, openWorld. The description adds beyond that: aggregated from CF analytics, no PII, data shape (pack, tool, count), and caching behavior (5min-1h). No contradictions.

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

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

Concise 4-5 sentence description, front-loaded with main output, then use cases, then additional details. Every sentence adds value 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?

Despite no output schema, the description fully explains the return structure (top tools, top packs, total call volume) and data shape (pack, tool, count), plus caching. Complete for agent decision-making.

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

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

Schema covers 100% of the single parameter (window) with enum and description. The description adds value by explaining the difference between shorter windows ('hot right now') and longer windows ('steady-state demand').

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window, with specific use cases. It distinguishes from siblings by focusing on aggregate usage trends.

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 (discovering hot data sources, confirming canonical tools, checking alignment). It does not explicitly list when not to use, but the context implies appropriate 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 declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds substantial behavioral context: how each mode operates, what it returns (ranked opportunities with reasoning), and why cross-event mode is necessary. No contradiction with annotations.

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

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

The description is a single, well-structured paragraph. It front-loads the core purpose, then details modes efficiently. 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 no output schema, the description explains return values (ranked opportunities with reasoning). It covers the tool's logic and modes. Minor omission: no mention of error handling or edge cases, but adequate for the complexity.

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

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

Schema coverage is 100% with detailed descriptions for both parameters. The description reinforces the parameter roles but does not add significant new meaning beyond 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's purpose: finding arbitrage opportunities via monotonicity violations. It explicitly names two modes (event vs topic) and differentiates itself from siblings like polymarket_edges by explaining the cross-event use case.

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

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

The description provides explicit guidance on when to use each mode, with concrete examples and rationale for cross-event mode. It lacks an explicit 'when not to use' but the context is clear enough for an AI agent to select appropriately.

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. The description adds substantial behavioral context: internal model details (lognormal, FRED, coinpaprika), efficiency (fetches each asset's price history once), grouping by asset, and ranking by |edge|. It also notes it's V1 and covers crypto-price bets, setting expectations. 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 efficient and well-structured: first sentence states purpose, then explains methodology and output. Every sentence adds value—no fluff. It is appropriately sized for the tool's complexity.

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

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

The description fully explains the tool's process and output: scanning top markets, grouping, fetching price history once, computing model probability, ranking by |edge|, and returning top N with suggested trade direction. Even without an output schema, the return format is clearly described. It also notes constraints (V1, crypto) to set expectations.

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 all three parameters (limit, window, min_edge_pp). The description does not add significant meaning beyond what the schema provides; it mentions defaults (limit 10, window 1wk, min_edge_pp 0.5) which are already 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 scans high-volume Polymarket markets and returns those with greatest disagreement between Pipeworx data and market price. It specifies the model (V1, lognormal from FRED + coinpaprika) and the process (scans, groups, fetches, computes, ranks). This differentiates it from siblings like 'polymarket_arbitrage' by focusing on edge magnitude for discovery.

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

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

The description explicitly says it's built for the 'what should I bet on today' question, indicating when to use: to discover opportunities without manual browsing. It does not explicitly state when not to use or name alternatives, but the purpose is specific enough to guide an agent. A mention of sibling tools like 'bet_research' would improve it.

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

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

Annotations (readOnlyHint=true, idempotentHint=true) already imply safe read operations. Description adds context about the arb signal and return structure 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?

Well-structured with clear sections and minimal redundancy, though slightly verbose in the return 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 no output schema, description adequately explains return format (leg prices, spreads). Completeness is high for a tool with two modes and complex return data.

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%; description enriches by explaining topic values and how explicit parameters override, 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?

Description clearly defines the tool as a cross-venue spread calculator between Kalshi and Polymarket, specifying two distinct modes (topic and explicit) and differentiating its purpose 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?

Explains two modes for different use cases but does not explicitly contrast with sibling tools or state when not to use this tool.

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

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

No annotations provided, so description carries full burden. States it retrieves memory, but doesn't disclose if memory persists across sessions or any side effects. Adequate but not detailed.

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

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

Two sentences, front-loaded with action and resource, no fluff.

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

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

Tool has one optional parameter and no output schema. Description covers the core usage well. Could mention return format or session persistence, but not critical given simplicity.

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

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

Schema coverage is 100% with the single 'key' parameter. Description adds context ('omit to list all keys') which goes beyond schema description, but is minimal.

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 action ('retrieve') and the resource ('stored memory by key'), and distinguishes two modes (specific key vs. list all).

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

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

Explicitly says when to use ('to retrieve context you saved earlier') and hints at alternatives (omit key to list all). Does not mention when not to use it or contrast with sibling tools like 'forget' or 'remember'.

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 parallel fan-out to multiple sources, accepted date formats, and return structure (structured changes, count, URIs). Could mention error handling or idempotency but covers key behavior.

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

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

Single paragraph, front-loaded with purpose, then details. No fluff. Could be slightly more structured but remains efficient and readable.

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

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

Given the complexity (multiple parallel sources), description covers what each source provides (SEC, GDELT, USPTO) and return format. Missing details on pagination, limits, or error handling, but overall adequate for a non-mutation tool.

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

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

Schema coverage is 100% with descriptions. Description adds value by giving concrete examples for 'since' (ISO and relative), defining 'value' as ticker or CIK, and suggesting typical monitoring windows. Also explains return format not in 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 'What's new about an entity since a given point in time' and explains the fan-out behavior for type='company'. It distinguishes the tool from siblings like entity_profile (static data) 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?

The description explicitly recommends use for 'brief me on what happened with X' or 'change-monitoring workflows.' It does not explicitly list when not to use or name alternatives, but the context is clear given sibling tool names.

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

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

No annotations provided, so description carries full burden. It discloses persistence behavior (authenticated vs anonymous) but does not mention size limits, overwrite behavior, or whether keys are case-sensitive. Adequate but not thorough.

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

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

Three sentences, each carrying distinct information: purpose, usage, and behavior. No filler. Could be slightly more structured but still concise.

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

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

Given no output schema and simple parameters, description covers purpose, usage, and persistence behavior adequately. Missing details like size limits or conflict resolution, but these are minor for a key-value store.

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, so baseline is 3. Description adds no additional parameter information beyond what schema already provides via examples and types.

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 stores a key-value pair in session memory. Verb 'store' and resource 'key-value pair' are specific, and the description distinguishes it from siblings 'forget' and 'recall' by focusing on saving 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?

Description says 'use this to save intermediate findings, user preferences, or context across tool calls', providing clear use cases. It does not explicitly mention when not to use it, but the positive guidance is strong.

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

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

No annotations are provided, so the description must carry the full burden. It mentions return values (ticker, CIK, name, URIs) but does not disclose behavioral traits such as read-only nature, rate limits, or error handling. The description implies a read operation but lacks explicit safety cues.

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 with no fluff. Every sentence adds value: first states purpose, second gives specifics and benefit.

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

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

Given no output schema, the description adequately explains return values. It covers purpose, usage, and input formats. Missing error handling or edge cases, but for a simple lookup tool it is fairly complete.

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

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

Schema coverage is 100%, but the description adds significant value by explaining accepted input formats (ticker, CIK, name) with examples, and clarifying that v1 only supports 'company' type. This goes beyond the enum description in the schema.

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

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

The description clearly states the tool resolves entities to canonical IDs, with a specific example for company type. It distinguishes itself from sibling tools like comtrade_* (trade data) and memory tools by focusing on entity resolution.

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 'Replaces 2–3 lookup calls' and provides context for v1 supporting company type. It implies when to use (to avoid multiple lookups) but does not explicitly state when not to use or mention alternatives.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds that it probes each entity with ai_visibility_check, ranks by score, and returns detailed metrics. No contradictions.

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

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

Two sentences plus a use case quote, front-loaded with purpose. Every sentence adds value, no fluff.

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

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

Describes return format (ranked list with score/confidence/signal density) despite no output schema. Covers inputs well. Minor omission: error handling (e.g., missing API key, entity count limits).

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 value: clarifies first entity is 'subject', entities limit 2-8, context disambiguates. Exceeds schema alone.

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

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

The description clearly states the tool compares AI visibility across multiple entities, using ai_visibility_check internally and ranking results. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (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: competitive AI-marketing audits comparing multiple entities. Implies for single entity use ai_visibility_check. Could be more explicit about 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?

Despite no annotations, the description discloses sources (SEC EDGAR + XBRL), returned data (verdict, structured form, value, citation, delta), and scope limitations (v1, US public companies). No side effects are mentioned but none expected.

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

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

Two sentences, front-loaded with purpose, no redundant information. Every sentence adds value.

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

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

Given only one parameter, no output schema, and no annotations, the description covers purpose, supported claims, and return values well. Minor gaps: error behavior and explicit limitations (e.g., only US public companies).

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 clear description of the 'claim' parameter. The description adds context about claim scope but does not significantly enhance the schema's explanation.

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 fact-checks natural-language claims against authoritative sources, specifically company-financial claims, with examples. It differentiates from siblings by its unique function.

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

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

It specifies supported claim types (company-financial) and mentions it replaces multiple agent calls, implying efficiency. However, it does not explicitly list when not to use or compare to siblings.

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