Shopify

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

The description fully discloses that Pipeworx selects the best tool and fills arguments, returning the result. Since no annotations are provided, the description carries the full burden and does so excellently by explaining the internal delegation behavior and expected outcome.

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 (three sentences) and front-loaded with the core purpose. The examples are helpful but could be trimmed to one or two. Overall, it is well-structured and efficient.

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

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

For a tool with one parameter and no output schema, the description adequately explains input and expected behavior. It does not detail what happens if the question is ambiguous or unsupported, but given the simplicity, it is sufficiently complete.

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

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

The description adds context that the 'question' parameter should be in plain English and gives examples, but the schema already describes it as 'Your question or request in natural language'. With 100% schema coverage, the description adds minimal additional value.

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

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

The description clearly states it takes a natural language question and returns an answer by selecting the appropriate tool and filling arguments. It provides concrete examples like 'What is the US trade deficit with China?', making the purpose unambiguous and distinct from siblings.

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

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

The description explains when to use it: when you want to ask a question in plain English without browsing tools or learning schemas. It implies you should use this instead of other tools when you don't know which specific tool to use. However, it does not explicitly state when not to use it (e.g., when you need direct access to a specific 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?

Beyond the readOnlyHint and destructiveHint annotations, the description adds significant behavioral detail: market resolution, bet classification, dynamic fan-out to data packs, and a market-vs-model comparison. No contradictions with annotations.

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

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

The description is a single paragraph, front-loaded with the core action. It is reasonably concise but includes a slightly promotional last sentence about conversion rates that could be trimmed for brevity.

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

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

No output schema exists, so the description should detail the return structure more. It mentions an 'evidence packet' and 'simple comparison' but lacks specifics. Error handling or prerequisites are not addressed, leaving gaps for a complex 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?

With 100% schema description coverage, the baseline is 3. The description adds value by explaining how the 'market' parameter accepts slugs, URLs, or question text, and describing the 'depth' parameter's quick vs thorough behavior.

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 using Pipeworx data, resolving the market, classifying the bet, and returning evidence. It distinguishes from siblings like ask_pipeworx by focusing specifically on betting edge for Polymarket markets.

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 concrete use cases are given ('should I bet on X?', etc.), but the description does not explicitly state when to avoid this tool or mention alternatives among siblings. The context is clear but lacks exclusion 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?

Without annotations, the description does well in disclosing behavior: it specifies that it returns paired data and resource URIs, and lists the exact metrics for each type. It does not mention potential side effects or cost, but for a read-only comparison tool, this is adequate. No contradictions with annotations.

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

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

The description is extremely concise: three sentences that front-load the main purpose, then detail the specifics per type, and finally highlight the efficiency benefit. Every sentence adds value with no redundancy.

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

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

Given the absence of an output schema, the description adequately covers the return data for both entity types, including specific fields and resource URIs. It covers the key aspects needed for an agent to understand what the tool does and what to expect.

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

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

The schema covers 100% of parameters, so baseline is 3. The description adds value by explaining the enum values for 'type' with concrete examples and providing context for the 'values' array with examples (e.g., tickers for company, drug names for drug), going beyond the schema's minimal descriptions.

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

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

The description clearly states that the tool compares 2-5 entities side by side, specifying the data returned for each type (company vs drug). It distinguishes itself from siblings by mentioning it replaces 8-15 sequential calls, though no sibling does the same comparison, making its purpose unique and well-defined.

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

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

The description provides clear usage context: when to compare entities and examples of input formats for both types. It lacks explicit 'when not to use' or alternatives, but the presence of similar tools like 'resolve_entity' might imply differentiate, though not mentioned directly. Overall, it gives sufficient 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 are provided, so the description must carry behavioral transparency. It describes the tool as searching and returning tools, but does not disclose details like whether it's read-only, whether it triggers side effects, or any rate limits. However, the description is clear enough for a search tool, earning a 3.

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: two sentences that efficiently convey purpose, usage context, and return value. No wasted words.

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

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

Given the tool is a search/discovery tool, the description is complete enough. It explains when to use it and what it returns. However, it lacks details on how results are ordered (e.g., relevance) and whether it supports pagination beyond the limit parameter. The absence of an output schema means the description could have mentioned the format of returned tools, but it's still adequate.

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

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

Schema coverage is 100%, with descriptions for both parameters. The description adds context by explaining the 'query' parameter should be a natural language description, providing examples, which goes beyond the schema. The 'limit' parameter is adequately described in the schema. Thus, a 4.

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

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

The description clearly states it searches the tool catalog by describing needs and returns relevant tools with names and descriptions. It specifies a concrete verb ('search') and resource ('tool catalog'), and distinguishes itself from siblings by being a meta-tool for tool 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 instructs to call this tool FIRST when there are 500+ tools available, providing a clear usage context. It also indicates the return type (names and descriptions) which helps in deciding when 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?

No annotations provided, so description bears full burden. It discloses output format (pipeworx:// citation URIs) and lists all bundled data sources. Does not mention side effects but implies read-only. Adequate transparency for a profile tool.

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

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

Four sentences, each serving a distinct purpose: purpose, details, output/efficiency, and alternative. Front-loaded with main verb. 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 explains return format and lists returned data. Mentions limitations (only company, no federal contracts). Provides guidance on parameter usage. Sufficiently complete for a profile tool.

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

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

Schema coverage is 100%, baseline 3. Description adds context: type limited to company, value accepts ticker or CIK, and advises using resolve_entity for names. This adds 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 returns 'full profile' including specific data types (SEC filings, revenue, patents, news, LEI). Distinguishes itself by saying it replaces 10-15 sequential calls and explicitly contrasts with sibling 'usa_recipient_profile' for federal contracts.

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

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

Provides explicit when-to-use: for comprehensive entity profile. Gives exclusion: for federal contracts, call usa_recipient_profile directly. Also hints at prerequisite: use resolve_entity if only have a name, as stated in the value parameter description.

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

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

No annotations are provided, so the description carries the burden. It states the tool deletes a memory, which implies mutability. However, it doesn't disclose whether the operation is irreversible, what happens if the key doesn't exist, or any side effects. This is adequate but not rich.

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 sentence with no unnecessary words. It is front-loaded with the action and object.

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

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

Given the tool's simplicity (1 required param, no output schema, no annotations), the description is minimally complete. It states what it does and how. However, it lacks error handling behavior and success confirmation details.

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

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

Schema description coverage is 100%, and the description adds no extra meaning beyond the schema. The description's 'by key' matches the schema's 'key' parameter. Baseline 3 is appropriate.

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

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

The description uses the verb 'Delete' and the resource 'stored memory', and specifies the action is 'by key'. It clearly distinguishes itself from siblings like 'remember' (create) and 'recall' (retrieve).

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

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

The description implies usage (when you want to delete a specific memory by its key) but does not provide explicit guidance on when not to use it or alternatives (e.g., if you want to delete all memories, or if the key doesn't exist).

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

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

With no annotations, the description carries full burden. It discloses rate limits ('Rate-limited to 5 messages per identifier per day') and implies a safe write operation, but does not mention authentication needs, side effects, or return format. The 'Free.' statement is ambiguous.

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 adding distinct value: purpose, usage instructions, and rate limit. It is efficiently structured, though the 'Free.' token could be integrated more clearly.

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

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

For a simple feedback tool with no output schema, the description adequately covers purpose, input format, and rate limiting. It does not need to explain return values. Slight room for improvement in behavioral transparency.

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

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

Schema description coverage is 100% with detailed parameter descriptions. The description adds value beyond the schema by advising agents to describe what they tried and to avoid including end-user prompts verbatim, improving usage quality.

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 'Send feedback to the Pipeworx team' and enumerates specific use cases (bug reports, feature requests, etc.), distinguishing it from sibling tools that are mostly data retrieval or memory operations.

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

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

The description explicitly lists appropriate use cases and provides guidance on content ('Describe what you tried in terms of Pipeworx tools/data — do not include the end-user's prompt verbatim') and mentions rate limits, but does not explicitly state when not to use the 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?

Description goes beyond readOnly annotations to detail behavioral traits: two modes, searching and grouping logic, return format (ranked opportunities with trade direction and reasoning). No contradictions with annotations.

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

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

Description is well-structured with two clearly delineated modes. No wasted sentences, though it is somewhat lengthy; front-loads the core purpose.

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

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

Despite no output schema, the description clearly explains what is returned (ranked opportunities, trade direction, reasoning). Covers both modes and their rationale, making the tool self-contained.

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

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

Schema coverage is 100% with descriptions, but the tool description adds significant context: explains the mode distinction, provides examples, and clarifies how each parameter triggers different behavior.

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?

Clear verb (find) + resource (arbitrage opportunities on Polymarket) + method (monotonicity violations). Two modes are explicitly distinguished, providing specific scope.

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

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

Explicitly explains when to use each mode: event for single-event monotonicity, topic for cross-event cases. Describes limitation of single-event mode and how topic mode addresses 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 already indicate read-only and non-destructive. The description adds significant context: it's V1, scans top markets, groups by asset, fetches price history once, uses a lognormal model from FRED + live coinpaprika price, computes model probability, ranks by |edge|, and returns top N with trade direction. No contradiction.

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

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

The description is a single paragraph of four sentences, front-loading purpose and then detailing process. It is fairly concise with no redundancy, though it could be slightly tighter.

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 three parameters, no output schema, and annotations, the description adequately covers the tool's purpose, model, and output (top N ranked by edge magnitude). It explains the process well enough for an agent to understand when to use it and what to expect.

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

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

Schema coverage is 100%, so baseline is 3. The description adds default values and limits (e.g., default 10, max 25 for limit; default 1wk for window; default 0.5 for min_edge_pp) but does not add meaning beyond the schema beyond these defaults.

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 finds discrepancies between Pipeworx data and market price, with specific mention of crypto-price bets, model used, and output. It distinguishes from siblings by focusing on opportunity discovery for the 'what should I bet on today' question.

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

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

The description explicitly says it's built for the 'what should I bet on today' question and helps agents/users discover opportunities without manual browsing. It implies when to use, but does not explicitly mention alternatives like polymarket_arbitrage or bet_research.

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

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

No annotations are provided, so the description carries the burden. It discloses that omitting key lists all memories, and implies retrieval is read-only. However, it does not mention side effects (e.g., whether retrieval marks memory as accessed) or persistence 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?

Two clear, front-loaded sentences. First sentence states purpose and usage pattern; second sentence adds context. No unnecessary words.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description is sufficient. It explains both modes of use. A small gap: does not specify the format of the returned memory (e.g., plain text, JSON), but with no output schema, some ambiguity 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% and the parameter 'key' is described. The description adds value by explaining the behavior when key is omitted (list all), which is not in the schema. No extra details on format are needed as key is a simple string.

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 memory by key or lists all memories when key is omitted. It specifies the resource ('stored memory') and action ('retrieve'), and distinguishes from sibling tools like 'remember' and 'forget'.

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

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

The description explicitly tells when to use (to retrieve context saved earlier) and how to use (omit key to list all). It does not mention alternatives, but the sibling list shows 'remember' and 'forget' cover other operations, making this tool's role clear.

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

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

No annotations provided, but the description discloses fan-out behavior to three sources in parallel, return fields (structured changes, count, URIs), and `since` format. Lacks error handling or rate limits; overall transparent.

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

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

Description is concise yet comprehensive, with clear front-loading of purpose, followed by details on entity type, parameter formats, return values, and usage. No unnecessary words.

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

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

Given three parameters, no output schema, and complexity of multiple sources, the description covers purpose, parameters, return format, and usage guidance well. Missing edge-case behavior (e.g., no changes found) but complete for typical use.

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

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

Schema coverage is 100%, and description adds significant value beyond schema. Explains `since` formats (ISO/relative) with examples, `value` as ticker or CIK, and type fan-out details. Highly informative.

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 reports 'what's new about an entity since a given point in time' and specifies behavior for type=company. It distinguishes from sibling tools like entity_profile by focusing on temporal changes.

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

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

Provides explicit usage context: 'Use for brief me on what happened with X or change-monitoring workflows.' It notes only company type is supported, which implies when not to use. Could mention alternatives but 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?

With no annotations, the description carries full burden. It discloses persistence behavior: 'Authenticated users get persistent memory; anonymous sessions last 24 hours', which is critical for an agent to understand memory lifetime.

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 with no wasted words. Each sentence adds value: what it does, when to use, and behavioral details.

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

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

Given the simple tool (2 params, no output schema), the description is nearly complete. It could optionally mention return value (e.g., success message) but not required.

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 no extra meaning beyond what the schema already provides (key and value fields are well-documented 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 'Store a key-value pair in your session memory', which is a specific verb+resource pair. It differentiates from siblings like 'recall' and 'forget' by its store operation.

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

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

The description provides clear usage context: 'Use this to save intermediate findings, user preferences, or context across tool calls'. However, it does not explicitly say when not to use it or compare to alternatives like 'recall'.

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 discloses input types, output fields, and version limitation (v1 supports 'company'). It does not cover error handling or rate limits, but is reasonably transparent.

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

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

Three sentences, front-loaded with purpose, then details, then benefit. No extraneous information.

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

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

Given no output schema and no annotations, the description sufficiently covers inputs, behavior, and output. Could mention error handling, but overall adequate.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds value by providing example values and clarifying the purpose beyond the schema.

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

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

Description clearly states the tool resolves an entity to canonical IDs, specifies it's for companies, and lists accepted inputs (ticker, CIK, name). This distinguishes it from sibling tools like ask_pipeworx or shopify tools.

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

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

Description mentions it replaces 2-3 lookup calls, implying efficiency, but does not explicitly state when to use vs alternatives or when not to use.

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

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

No annotations are provided, so the description carries full burden. It does not disclose any side effects, rate limits, permissions, or error conditions. Simply stating 'Get a single order' provides minimal transparency beyond the name.

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 sentence, no fluff. It is appropriately concise for a simple retrieval operation, though could benefit from additional context if needed.

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

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

Given no output schema and no annotations, the description is insufficient. It does not explain what data the order contains, any field options, or behavior when order is not found.

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

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

Schema coverage is 100%, so baseline is 3. The description adds no extra meaning beyond what the schema already provides (id, _shop, _apiKey).

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 ('Get'), resource ('order'), and qualifier ('single by ID') with the source ('from a Shopify store'). It is distinct from siblings like 'shopify_list_orders' which retrieves multiple orders.

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

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

No guidance on when to use this tool vs alternatives (e.g., for batch retrieval use shopify_list_orders). No prerequisites or context for using the tool.

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

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

Annotations are empty, so the description carries the full burden. It describes the basic action (get) and mentions the source (Shopify store), but doesn't disclose side effects (none expected), rate limits, authentication details beyond parameters, or error cases. Acceptable for a simple read operation, but could be improved.

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 sentence, front-loaded with the action and resource. No wasted words. Efficient and clear.

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

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

Given the tool's simplicity (3 parameters, no output schema, no nested objects), the description is fairly complete. However, it doesn't mention the return format (e.g., product object with fields) or potential errors (e.g., not found). For a simple read tool, this is acceptable but could be slightly more informative.

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% (all three parameters have descriptions in the schema). The description does not add any additional meaning beyond the schema. Baseline 3 is appropriate since the schema already documents parameters adequately.

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 'Get a single product by ID from a Shopify store,' which clearly identifies the verb (Get), resource (product), and scope (by ID from a Shopify store). It distinguishes from sibling tools like shopify_list_products (list vs. single) and shopify_get_order (product vs. order). However, it lacks explicit mention that it only retrieves one product, which is implied but not explicit.

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

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

No guidance on when to use this tool versus alternatives. For example, it doesn't mention that shopify_list_products should be used to get multiple products or for searching. It also doesn't mention prerequisites like having a valid API key or shop domain, though those are in the input schema.

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 disclose behavior. It does not mention pagination, rate limits, authentication requirements beyond schema fields, or any side effects. The tool lists customers but does not clarify if it returns all or filtered results.

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

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

The description is a single sentence, concise and to the point. It is front-loaded with the action and resource, but lacks any additional details.

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

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

Given the tool has 3 parameters, no output schema, and no annotations, the description is too minimal. It does not explain return values, filtering capabilities, or pagination, leaving agents without critical usage information.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the schema provides. Parameters are documented in the schema but the description does not explain them.

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 the tool lists customers from a Shopify store. However, it does not distinguish this tool from siblings like shopify_list_orders or shopify_list_products, and the verb 'list' is 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?

No guidance on when to use this tool versus alternatives like shopify_get_order or shopify_list_orders. No mention of prerequisites or context for use.

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

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

Annotations are empty, so the description must disclose behavior. It indicates a read operation (list) and mentions optional filtering, but lacks details on pagination, ordering, or response format.

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

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

One short sentence, no fluff. Could be slightly more informative without adding length, but it's 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?

Tool has 4 params, no output schema, no annotations. The description covers the basic purpose but lacks details on pagination, rate limits, or return structure. Adequate for a simple list operation.

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 each parameter is documented in the schema. The description adds the default status and limit, but the schema already covers that. No additional semantics beyond schema.

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

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

The description clearly states the tool lists orders from a Shopify store and can optionally filter by status. However, it does not differentiate from sibling tools like shopify_get_order, which is a different operation.

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

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

No guidance on when to use this tool versus alternatives like shopify_get_order for single orders, or when the status filter is appropriate. No mention of prerequisites or context for use.

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

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

No annotations are provided, so the description carries full burden. It mentions default return limit (50) and max (250), which adds behavioral context beyond the schema. However, it does not disclose pagination behavior, potential rate limits, or whether results are ordered.

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 sentence with no waste. Front-loaded with purpose, then key constraint (up to 50). Could be slightly more structured 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?

Given 3 required parameters, no output schema, and no annotations, the description provides minimal completeness. It covers purpose and limit default but lacks behavioral details like pagination, ordering, or what data is returned per product. A 3 is adequate for a simple list tool.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds no additional meaning beyond schema; it mentions the default limit but does not explain the _shop or _apiKey parameters beyond what schema says.

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 'List products from a Shopify store', which is a specific verb and resource. It distinguishes from siblings like shopify_get_product (single product) and shopify_list_orders (orders). However, it does not explicitly differentiate from other list tools.

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

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

Description implies usage for listing products but provides no guidance on when to use this vs alternatives like shopify_get_product for single product details. No exclusion criteria or prerequisites beyond the required parameters.

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 full burden; it discloses the return verdict types, citation format, and percent delta, and explains it replaces sequential NL parsing, entity resolution, and data lookup. It does not mention auth or rate limits, but given the read-only nature, it's adequate.

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

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

The description is two sentences with no waste: first sentence states the main purpose, second sentence enriches with scope, return structure, and value proposition. Front-loaded and efficient.

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

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

Given a single required parameter, no nested objects, and no output schema, the description adequately explains the tool's behavior, return fields, and scope limitations (v1, company-financial). It leaves little ambiguity for an AI agent.

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

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

With 100% schema description coverage, the baseline is 3; the description adds value by providing concrete examples and specifying natural-language format expectations beyond the schema's generic 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 tool fact-checks natural-language claims against authoritative sources, with specific support for company-financial claims of US public companies. It implicitly distinguishes from siblings like ask_pipeworx by positioning itself as a composite tool replacing multiple agent 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 provides clear context on the domain (company-financial) and data sources (SEC EDGAR + XBRL), but lacks explicit when-not-to-use guidance or alternatives for non-financial claims.

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