Comtrade

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?

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?

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?

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?

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.