Apology

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

With no annotations, the description carries full burden. It discloses the return of tailored text but omits any behavioral traits like content policies, length limits, or 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?

Two sentences, front-loaded with purpose and key parameters. Every word earns its place; 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?

Given the tool's simplicity and existence of output schema, the description covers the main aspects: input parameters and return type. Slight omission of medium parameter, 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 0%, so description must compensate. It mentions sincerity, relationship, and offense, but not medium. Examples in schema are not in description. Some examples of sincerity ('sincere') don't match schema enums ('genuine'). Adds partial value.

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

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

The description clearly states the tool generates a personalized apology, specifying the verb 'Generate' and the resource 'apology'. It also distinguishes from sibling tools, which are unrelated, making the purpose unambiguous.

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 broad use ('for any situation') but lacks explicit guidance on when not to use or alternatives. However, since siblings are unrelated, no exclusions are necessary, and the context is clear.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It explains that Pipeworx picks the right tool and fills arguments, implying autonomous action. It does not mention any side effects, latency, error handling, or whether the tool can handle multi-step requests. The description is adequate but not exhaustive.

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

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

The description is concise at three sentences plus examples. It front-loads the main action and then provides context and examples. The examples are valuable but could be more tightly integrated. No waste, but could be slightly more structured.

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

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

Given the tool's simplicity (one parameter, no output schema, no annotations), the description is largely complete. It explains the core behavior, provides examples, and sets expectations about automation. It does not discuss failure modes or limitations, but the complexity is low enough that this is acceptable.

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

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

The only parameter 'question' has 100% schema coverage with its description 'Your question or request in natural language'. The description adds examples and context about using plain English, which goes slightly beyond the schema but not significantly. Baseline 3 is appropriate as schema coverage is high.

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: it accepts a natural language question and returns an answer by selecting the best data source and filling arguments. It distinguishes itself from siblings by emphasizing that it abstracts away tool browsing and schema learning, which is not true for sibling tools like discover_tools or apology_generate.

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

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

The description provides clear guidance on when to use this tool: when you want to ask a question in plain English without needing to know schemas or tool names. It gives three specific examples. However, it does not explicitly state when not to use it or mention alternatives like discover_tools for discovering capabilities.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds significant behavioral context: it resolves markets, classifies bets, fans out to relevant packs (e.g., crypto+fred+gdelt for BTC bets), and returns an evidence packet with a market-vs-model comparison. This goes well beyond the basic read-only and open-world hints.

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 relatively long but well-structured with front-loaded purpose. Each sentence adds unique value, such as the fan-out behavior and the call-to-action for agents. It could be slightly more concise, but the detail is justified given the tool's role as a core demo product.

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 purpose, usage, parameter behavior, return type (evidence packet + comparison), and internal logic (fans out to packs). Given no output schema, the description fully explains what the tool returns. Complexity is moderate, but the description ensures an agent knows exactly 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 value by explaining the depth parameter's behavior (quick vs thorough) and default. For the market parameter, it reiterates the three input formats (slug, URL, question text) which the schema already covers, but adds context by showing examples. Overall, it enhances understanding beyond the schema alone.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, resolving markets, classifying bets, and returning evidence. It distinguishes from siblings by positioning as a core demo product that coordinates multiple packs, unlike generic tools like ask_pipeworx or validate_claim.

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

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

The description explicitly lists use cases: "should I bet on X?", "what does the data say about this Polymarket market?", "is there edge in this bet?". While it doesn't explicitly state when not to use, the specificity makes the context clear. Alternative tools exist but are not named, but the description implies this is the go-to for 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 provided, so the description carries full burden. It discloses return data (paired values, URIs) and data sources (SEC, FDA) but does not mention side effects, destructiveness, or rate limits. For a read-like operation this is acceptable but not fully 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?

The description is three sentences, front-loads key information (what, how many, types), and every sentence adds 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's moderate complexity and lack of output schema, the description covers the essentials: purpose, parameters, return format, and efficiency gains. It could mention pagination or error handling but is sufficient 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?

The input schema has full description coverage (100%). The description adds value by explaining the return data for each type and providing examples for the values parameter, going beyond the schema.

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

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

The description clearly specifies the tool's action (compare 2-5 entities side by side) and the resources (company or drug with specific metrics). It distinguishes from siblings by noting it replaces 8-15 sequential 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 implicitly states when to use (comparing entities efficiently) but lacks explicit guidance on when not to use or alternatives. The context is clear enough for an agent to select it over sequential calls.

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

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

With no annotations, the description carries the burden. It explains the tool performs a search and returns results, but doesn't detail whether it's read-only (assumed), any rate limits, or what happens with ambiguous queries. However, for a search tool, this is sufficient.

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 and immediate action directive. Every sentence earns its place: first explains what it does, second tells when to use it. 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?

Given it's a search tool with 2 parameters, no output schema, and no annotations, the description fully covers its role and usage. The instruction to call it first provides complete context for integration with sibling tools.

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

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

Schema coverage is 100%, so baseline is 3. The description doesn't add meaning beyond schema descriptions for 'query' and 'limit', but the example in the query description ('e.g., "analyze housing market trends"') provides helpful guidance not present 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?

Clearly states it searches the tool catalog by description, returns relevant tools with names and descriptions. Specific verb 'search' and resource 'Pipeworx tool catalog' distinguish it from sibling tools like 'recall' or 'remember'.

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 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' Provides clear context for when to use this tool (as a discovery step) and implies it's an alternative to manually searching or using other tools.

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

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

Discloses types of data returned (SEC filings, XBRL, patents, news, LEI), output format (pipeworx:// citation URIs), and performance benefit (replaces 10-15 calls). No annotations, but description fully covers behavioral traits.

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 with no redundant sentences. Purpose stated first, then supported details, then usage alternative. 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?

Thoroughly addresses the tool's complexity with clear input requirements, output expectations, and cross-reference to a sibling tool. No gaps given the 2-param schema and no output schema.

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

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

Adds meaning beyond schema by explaining type='company' is the only supported value, how to format value (ticker or zero-padded CIK), and that names require prior resolution. Schema coverage 100% provides baseline but description enriches usage.

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

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

Clearly states the tool returns a full profile of an entity across multiple data sources with specific verb 'returns'. Distinguishes from siblings like resolve_entity and compare_entities by describing its consolidated nature.

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 advises when to use ('full profile'), when not to use (federal contracts should use usa_recipient_profile), and provides step-by-step guidance on input (use resolve_entity if only name).

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 states deletion behavior but does not disclose irreversible effects, required permissions, or side effects. However, for a simple key-based deletion, the transparency is 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?

Single concise sentence, front-loaded with verb and resource, no wasted words.

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

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

Given the tool's simplicity (1 parameter, no output schema), the description is minimally complete. It covers what the tool does but lacks return value info and edge cases.

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% (key described as 'Memory key to delete'). Description adds no extra meaning beyond the schema; baseline 3 is appropriate.

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

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

The description 'Delete a stored memory by key' uses a specific verb (delete) and resource (stored memory), clearly distinguishing it 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 deletion usage but does not explicitly state when to use this tool versus alternatives like 'remember' or 'recall', nor does it provide any exclusion criteria.

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 reveals a rate limit ('5 messages per identifier per day') which is a behavioral constraint. However, it does not disclose error behavior on exceeding the limit, success confirmation, or any side effects. The mention of 'Free' 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 extremely concise—two sentences plus additional details (rate limit, free). Every sentence serves a purpose with no 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?

For a feedback tool with 3 parameters and no output schema, the description covers purpose, usage rules, and rate limiting. It could mention whether a confirmation is returned, but overall it provides sufficient context for an AI agent to use it effectively.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds value by giving specific guidelines for the message parameter ('Describe what you tried... do not include the end-user's prompt verbatim'), which aids correct usage beyond the schema's plain text requirement.

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 'Send feedback to the Pipeworx team' and lists specific use cases (bug reports, feature requests, missing data, praise). It clearly differentiates from sibling tools, which focus on questioning, discovery, 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 provides clear guidance on when to use the tool (for feedback types) and explicit prohibitions ('do not include the end-user's prompt verbatim'). It includes rate limit information but does not specify alternatives or when not to use it, though siblings are distinct 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false. The description adds behavioral context: it is a read-only analysis, returns ranked opportunities with reasoning, and explains the two modes' behaviors.

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

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

The description is well-structured with clear sections for purpose, modes, and output. It is somewhat lengthy but every sentence adds value. Slightly verbose, but still within acceptable limits for a complex tool.

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

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

No output schema, but the description states the return format (ranked opportunities with reasoning). The tool is complex, but the description covers purpose, mode selection, parameter usage, and output. Complete for its domain.

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

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

Both parameters (event, topic) are fully described in the schema. The description adds rich context: examples of slugs/topics, how each mode uses the parameter, and the reasoning for cross-event mode. No gaps.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations. It distinguishes two modes ('event' and 'topic') with specific purposes, making it distinct from siblings like 'bet_research' or 'polymarket_edges'.

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

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

Provides explicit when-to-use guidance for each mode, with examples and a concrete case where cross-event mode is needed (May≤June rule). This helps the agent choose correctly between modes.

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?

Even with readOnlyHint=true and destructiveHint=false already provided, description adds rich detail: uses FRED+FIMFIVElognormal model, coinpaprika price, groups by asset, fetches price history once, computes model probability, ranks by |edge|. No contradictions.

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

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

Description is slightly long but well-structured with clear narrative: what it does, how it works, when to use. 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?

No output schema, but description explains return format (top N ranked by edge magnitude with suggested direction). Covers model, sources, and intent. Reasonably complete 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?

Schema coverage is 100% with descriptions. Description adds context like default values (default 10, default 1wk) but does not significantly extend parameter 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 it scans top Polymarket markets, finds where Pipeworx data disagrees with market price, and returns ranked edges. Distinguishes from sibling polymarket_arbitrage by focusing on 'what to bet on today'.

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

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

Explicitly states built for discovering opportunities without manual paging. Could mention when not to use (e.g., if Pipeworx data outdated), but context is clear.

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

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

Describes that omitting key lists all memories, which is not in annotations. No annotations provided, so description carries full burden; it does well but could mention idempotency or potential size limits.

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 unnecessary 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 no output schema and simple tool, description is adequate. Could mention return format (e.g., object with key-value) but not critical.

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

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

Schema coverage is 100% with clear parameter description. The description adds context that omitting key lists all, which is not in schema. No param info in description beyond that, but schema already suffices.

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-resource pair 'Retrieve a previously stored memory by key, or list all stored memories' distinguishes two modes, differentiating it 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?

Explicitly states when to use: 'Use this to retrieve context you saved earlier in the session or in previous sessions.' Also implies when not to use (no mention of forgetting or generating).

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?

Discloses behavioral traits beyond annotations: fans out to multiple sources in parallel for company type, returns structured changes with count and URIs. No annotations provided, so description carries full burden. It covers output and parallel execution but omits potential error handling or rate limits.

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: four sentences that front-load the purpose, then detail behavior and output. Every sentence adds necessary information without redundancy. Ideal length for quick comprehension.

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

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

Given no output schema, the description explains the return structure (structured changes, count, URIs) and the parallel processing of multiple data sources. It also specifies the entity type constraint. For a tool with three parameters, this is fully 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 coverage is 100%, so baseline is 3. Description adds examples for `since` (e.g., '7d', '1y') and recommends typical values ('30d' or '1m'). It also reinforces that `type` is limited to 'company'. These additions add value beyond the schema.

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

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

The description clearly states the tool's function: retrieving recent changes for an entity since a given time. It uses specific verbs like 'brief me' and 'monitoring', and differentiates from siblings by focusing on change-monitoring rather than static profiles or comparisons.

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 suggests use cases: 'brief me on what happened with X' and change-monitoring workflows. However, it does not mention when not to use this tool or provide alternatives, such as using entity_profile for static info or compare_entities for side-by-side comparisons.

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

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

No annotations provided, so description carries full burden. Discloses persistence behavior (authenticated vs 24-hour anonymous) and storage purpose. However, does not mention potential side effects, overwrite behavior for existing keys, or character limits. Adequate but not exhaustive.

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

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

Three sentences, front-loaded with core action. First sentence defines purpose, second gives usage guidance, third adds persistence behavior. No wasted words. Could be slightly more concise by merging sentences, but structure is logical.

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 tool has only 2 simple string parameters, no output schema, and no nested objects, description is complete enough. Explains storage behavior and use cases. Lacks only minor details like overwrite policy or maximum key/value length, but these are not critical for a simple memory 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?

Schema coverage is 100%, so baseline is 3. Description adds value beyond schema by explaining the context of use (e.g., 'intermediate findings, user preferences') and persistence implications. The schema already describes parameters well with examples, but description reinforces their purpose.

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

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

Description clearly states verb (store), resource (key-value pair in session memory), and purpose (save intermediate findings, user preferences, context). Differentiates from sibling tools like 'recall' (retrieval) and 'forget' (deletion) by explicitly mentioning memory storage.

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 for when to use ('save intermediate findings, user preferences, or context across tool calls') and gives behavioral details about persistence (authenticated vs anonymous). Does not explicitly mention when not to use or provide alternative tool names, but guidance is sufficient.

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

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

No annotations provided; description does not disclose potential side effects, authorization requirements, or failure modes. Only mentions return values, leaving behavioral details incomplete.

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 redundancy. All information is relevant and front-loaded, efficiently conveying key 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?

For a simple two-parameter tool with no output schema, description adequately covers inputs, outputs, and version constraints. Lacks error handling or rate limit info but sufficient for basic usage.

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

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

Schema coverage is 100%, baseline 3. Description enriches parameters with concrete examples (e.g., 'AAPL', '0000320193', 'Apple') and clarifies the enum constraint, adding meaning beyond the schema.

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

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

Clearly states the tool resolves entities to canonical IDs across data sources in a single call. Describes specific use case and distinguishes from sibling tools like ask_pipeworx 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?

Provides explicit examples of accepted inputs (ticker, CIK, name) and outputs. Implies efficiency benefit over multiple calls, but lacks explicit when-not-to-use or alternative tools.

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

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

With no annotations provided, the description carries the full burden. It discloses the data sources (SEC EDGAR + XBRL), the verdict types (confirmed, refuted, etc.), and the return structure (structured form, actual value, citation, percent delta). It also notes efficiency gains over sequential calls. Missing details on failure modes or auth requirements, but overall substantial transparency.

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

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

The description is concise: two sentences that front-load the core purpose and then detail the outputs and efficiency gains. Every sentence adds substantive information without redundancy, achieving high density of useful information.

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

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

Despite no output schema, the description explicitly lists what the tool returns (verdict, structured form, actual value with citation, percent delta). For a single-parameter tool with clear domain constraints, this is sufficient for an agent to understand inputs and outputs.

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

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

The input schema provides 100% coverage with a clear description for the single parameter 'claim'. The description adds value by providing concrete examples ('Apple's FY2024 revenue was $400 billion'), which help the agent understand formatting and scope beyond the schema's brief text.

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: 'Fact-check a natural-language claim against authoritative sources.' It specifies the supported domain (company-financial claims) and the output (verdict with structured details). This distinguishes it from sibling tools like ask_pipeworx (general Q&A) and compare_entities (comparison), providing clear differentiation.

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

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

The description indicates when to use the tool: 'Replaces 4–6 sequential agent calls,' implying it consolidates multiple steps. It also explicitly limits scope to 'v1 supports company-financial claims' for US public companies. However, it does not explicitly state when not to use it (e.g., for non-financial or non-US claims), leaving minor ambiguity.

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