Phoenix Number

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

No annotations are provided, so the description must disclose behavior. It explains that the tool picks the best data source and fills arguments, revealing its meta-nature. However, it doesn't specify potential latency, fallback behavior, or if it can fail, but given no annotations, this 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?

The description is concise (3 sentences + examples) and front-loaded with the core action. Examples add useful context without being verbose. Could be slightly tighter by integrating examples into the main text.

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 simplicity (1 parameter, no output schema, no annotations), the description is complete enough. It explains how the tool works and what to expect. No major gaps identified for this meta-tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the single parameter 'question' as a natural language request and provides examples of valid questions, enhancing understanding beyond the schema.

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

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

The description clearly states the tool's purpose: ask a question in plain English and get an answer. It explains that Pipeworx selects the appropriate tool and fills arguments, eliminating the need for browsing. Examples concretely illustrate use cases.

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

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

The description implies when to use this tool: when you have a question and want the system to handle tool selection. It doesn't explicitly state when not to use it or list alternatives, but the context of being a meta-tool 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?

The description thoroughly explains internal behavior: it resolves the market, classifies bets into categories (crypto price, Fed rate, etc.), fans out to appropriate data packs, and returns a comparison. This goes beyond the annotations' readOnlyHint and openWorldHint by detailing the process and output.

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

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

The description is a single, well-structured paragraph that is front-loaded with the main purpose. Each sentence adds value, from input to output to use cases, without redundancy. It is comprehensive yet 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 the tool's complexity and absence of an output schema, the description adequately covers return values (evidence packet, comparison) and internal logic (fan-out to packs). It leaves no major gaps, making it complete for an agent to understand and use 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?

The schema already covers both parameters with descriptions (100% coverage). The description adds context about the depth parameter (quick vs thorough) and clarifies the market parameter's accepted formats, enhancing understanding beyond the schema. However, it does not introduce new parameter details.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data. It specifies input formats (slug, URL, question text) and output (evidence packet, market-vs-model comparison). It positions itself as the core demo product, distinguishing it from sibling tools that may require separate data 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 provides explicit use cases: 'should I bet on X?', 'what does the data say about this Polymarket market?', 'is there edge in this bet?'. It emphasizes that this tool is superior to agents discovering packs themselves, offering clear guidance on 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 carries full burden. It states return values (paired data + URIs) and data sources (SEC EDGAR, FDA), but fails to disclose safety (read-only/readWrite), authentication, permissions, or error states. Adequate but not thorough.

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

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

Two sentences covering purpose, type-specific details, return format, and efficiency gain. Compact and front-loaded, though the return description could be 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?

With no output schema, description summarizes return as 'paired data + pipeworx:// resource URIs', which is sufficient for a simple tool but leaves some ambiguity about exact structure. Parameters are well-documented, so overall adequate given low complexity.

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

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

Schema covers 100% of parameters. Description adds context beyond schema by giving examples (e.g., ['AAPL','MSFT']) and explaining type-specific fields (revenue, net income for company; adverse-event reports for drug), enhancing clarity for agent selection and invocation.

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 compares 2-5 entities side-by-side, specifying two types (company and drug) and the fields retrieved for each. It distinguishes by noting it replaces multiple sequential calls, but does not directly compare with sibling tools like ask_pipeworx.

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

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

Describes when to use (to compare entities in one call) and implies it avoids sequential calls, but does not explicitly state when not to use it or provide alternatives among siblings.

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

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

No annotations are provided, so the description must cover behavioral aspects. It states the tool returns 'most relevant tools with names and descriptions,' implying a non-destructive read operation. However, it does not disclose rate limits, response format details, or any side effects. Given the absence of annotations, a score of 3 is appropriate as it provides basic behavioral context but lacks depth.

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

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

The description is concise with three sentences, each adding value: first defines purpose, second describes output, third provides usage guidance. No redundant or filler content.

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

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

Given the tool's simplicity (2 parameters, no output schema, no nested objects), the description is complete enough. It explains purpose, when to use, and what returns. Minor omission: could mention that query is required, but that's already clear from the schema. No output schema reduces the need to explain return values.

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%, meaning both parameters are already documented in the input schema. The description adds no additional parameter semantics beyond what the schema provides. Baseline 3 is correct since the schema covers all parameters, and the description does not enhance understanding.

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: 'Search the Pipeworx tool catalog by describing what you need.' It specifies the action (search), resource (tool catalog), and method (natural language description). The tool is uniquely positioned as a discovery mechanism, distinct from siblings like ask_pipeworx or recall.

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

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

The description explicitly states when to use this tool: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This provides clear guidance on prioritization and context, helping the agent decide when to invoke this tool over others.

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 full burden. It discloses that the tool returns pipeworx:// citation URIs rather than raw data and lists the data types. However, it does not mention potential delays or failure modes.

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 informative but packed with detail. It front-loads the purpose and lists contents efficiently. A slight reduction in length could improve conciseness, but it remains clear and well-organized.

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 output schema and annotations, the description provides sufficient context: what data is returned, how to use the parameters, what is not included (federal contracts), and how it compares to alternatives. It is self-contained and actionable.

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

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

The description adds significant value beyond the schema: it clarifies that type is currently limited to 'company', explains value can be ticker or CIK, and explicitly states names are not supported, directing to resolve_entity. This fully compensates for the schema's basic 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 it returns a full profile of an entity with specific data sources (SEC filings, XBRL, patents, news, LEI). It distinguishes itself by claiming to replace 10-15 sequential calls and names a specific alternative 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?

Explicitly directs agents to use usa_recipient_profile for federal contracts and implies this tool should be used when a comprehensive profile is needed efficiently. Also notes that names are not supported and suggests resolve_entity first.

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

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

No annotations are provided, so the description carries full burden. It states the action is destructive (delete), but does not disclose whether deletion is permanent, if confirmation is needed, or if there are side effects. It's adequate but minimal.

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

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

The description is one short sentence that efficiently conveys the tool's purpose. Every word is necessary, no fluff. Front-loaded with 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 param, no output schema, no nested objects), the description is complete enough. It tells the agent exactly what the tool does and what parameter is needed. However, it could mention that the operation is irreversible or if the key must exist.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. The description reinforces the purpose but adds no new meaning beyond the schema. However, since coverage is high, baseline is 3; the description is consistent and clear, warranting a 4.

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

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

The description uses a clear verb 'Delete' and specific resource 'stored memory by key'. It concisely states the tool's action and distinguishes it from sibling tools like 'remember' (store) and 'recall' (retrieve).

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

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

The description implies when to use (when you need to delete a memory) but provides no guidance on when not to use, prerequisites, or alternatives. The sibling context suggests it's for deletion, but no explicit exclusions are given.

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

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

The description discloses it returns a single numeric value, but does not specify randomness quality or security limitations. Annotations are empty, so the description carries the burden and is adequate for a simple utility.

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 zero wasted words. Front-loaded with key action and 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?

Given the output schema exists and the tool has no parameters, the description covers the essential behavior. It is complete for the tool's simplicity.

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

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

No parameters exist; baseline score of 4 applies. The description adds no parameter information but none is needed.

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

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

The description clearly states the tool generates a random number for testing or placeholder use, with a specific verb and resource. It is distinct from sibling tools which focus on entity queries and feedback.

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 usage for testing or placeholder values, providing clear context. However, it does not explicitly mention alternatives or when not to use this tool, though no siblings serve a similar purpose.

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 rate limiting and content constraints, which is helpful. However, with no annotations provided, the description could better explain what happens after submission (e.g., acknowledgment, ticket creation). The 'Free' note 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?

Four concise, front-loaded sentences. Each sentence adds distinct value: purpose, allowed content, forbidden content, and rate limit. 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?

For a simple feedback tool with no output schema, the description covers key aspects: what to include, what to avoid, and constraints. Could mention expected response or confirmation, but not critically missing for a low-complexity task.

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

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

Schema description coverage is 100%, so the schema already documents parameters well. The description adds no significant new meaning beyond the schema, though it reinforces that message should be specific and tool-related.

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 'Send feedback to the Pipeworx team' and enumerates specific use cases (bug reports, feature requests, missing data, praise). Distinguishes well from sibling tools like ask_pipeworx (for queries) and discover_tools (for exploration).

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 instructs users to describe what they tried in terms of Pipeworx tools/data and to exclude the end-user's prompt. Also mentions rate limit (5 per day). While it doesn't explicitly state when not to use, the context is clear given sibling tool purposes.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds detailed behavioral context: it walks markets, groups them, checks monotonicity, and returns ranked opportunities with reasoning. 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 well-structured: first sentence states purpose, then explicitly describes two modes. Every sentence contributes value, and the content is front-loaded. 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 moderate complexity (two modes, cross-event search), the description covers purpose, mode selection, parameter usage, and output format. Annotations cover safety. No output schema is needed as the description explains return values.

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

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

Input schema covers 100% of parameters with descriptions. The description adds significant value by explaining the mode-specific usage, examples, and the purpose of each parameter beyond what the schema provides.

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 'Find arbitrage opportunities on Polymarket by checking for monotonicity violations across related markets,' with specific verb and resource. It distinguishes itself from siblings like polymarket_edges and bet_research by focusing on arbitrage and monotonicity checking.

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

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

The description explains two modes ('event' and 'topic') with explicit use cases and examples, but does not compare directly to sibling tools or state when not to use this tool. However, the context is clear enough for appropriate invocation.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds detailed behavioral traits: it uses external data sources (FRED, coinpaprika), computes model probabilities, ranks by edge, and returns suggestions. 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 concise yet comprehensive, starting with the main purpose, then detailing the approach, steps, and output. 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 no output schema, the description adequately explains the return format (top N edges with direction). It covers the algorithm and purpose. Minor gaps like error handling or data freshness are acceptable given the openWorldHint annotation.

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%, but the description adds context beyond individual parameter descriptions, such as explaining how parameters like 'limit' relate to the ranking process and the algorithm's grouping behavior. This enhances understanding.

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 to find where Pipeworx data disagrees with market price, using a specific verb ('scan and return') and resource ('Polymarket markets'). It differentiates from sibling tools like 'polymarket_arbitrage' by focusing on discovering opportunities rather than executing trades.

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 targets the 'what should I bet on today' question, providing clear context for when to use the tool. It does not explicitly mention when not to use it or name alternatives, but the use case is well-defined.

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

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

No annotations are provided, so the description carries the full burden. It explains the behavior (retrieve by key or list all) but does not mention any potential side effects, authorization needs, or limits. It 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 two sentences, front-loaded with the primary purpose. The second sentence provides usage context. It is concise and efficient, though 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?

The tool has one optional parameter and no output schema. The description covers the basic functionality, but lacks details on return format, error cases, or memory persistence behavior. It is minimally complete for the given complexity.

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

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

Schema coverage is 100%, and the description adds some context: omitting the key lists all memories. However, it does not elaborate on the format of the key or any constraints, so it adds marginal 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 uses a specific verb 'retrieve' and resource 'memory by key', and explicitly covers the dual mode (by key or list all). It distinguishes itself from 'remember' (store) and 'forget' (delete), which are sibling tools.

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

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

The description states when to use this tool ('retrieve context you saved earlier'), but does not explicitly state when not to use it or provide alternatives for retrieval beyond listing. However, 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, the description carries the full burden. It transparently explains parallel fan-out to multiple sources, the two accepted `since` formats, and the return structure (structured changes, total_changes, URIs). No hidden behaviors are omitted.

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 of about 80 words, front-loaded with the core action, then expanding on details and usage. Every sentence earns its place; no filler.

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

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

Given the multi-source complexity and three parameters, the description covers inputs, fan-out behavior, and return shape. It lacks mention of pagination or error handling, but for a monitoring tool the provided detail is sufficient for initial 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%, but the description adds value by explaining `since` formats with examples ('7d', '30d', '1y') and usage tips ('Use 30d for typical monitoring'). It also clarifies that `type` only supports 'company' currently. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'What's new about an entity since a given point in time.' It specifies the entity type (company) and breaks down the data sources (SEC EDGAR, GDELT, USPTO). This uniquely distinguishes it from sibling tools like entity_profile and compare_entities.

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

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

The description explicitly recommends usage for 'brief me on what happened with X' or change-monitoring workflows. It does not mention when not to use or list alternatives, but the use case is clear enough for most scenarios.

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

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

With no annotations, the description carries full burden. It discloses persistence behavior and session limits, which is good, but lacks details on overwrite behavior, storage limits, or data retrieval implications.

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 concise sentences front-loaded with the core action, then usage guidance, then persistence details. Every sentence adds value with no waste.

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

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

Given the tool's simplicity (2 required params, no output schema), the description is nearly complete. It covers purpose, usage, and behavioral aspects, though a note on idempotency or overwrite behavior would make it fully complete.

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

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

Schema description coverage is 100%, so the schema already explains the parameters. The description adds general context but no additional semantics beyond what the schema provides, warranting the baseline of 3.

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 stores a key-value pair in session memory, with specific use cases (intermediate findings, user preferences, context) that distinguish it from sibling tools like 'recall' and 'forget'.

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

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

The description explains when to use (to save context across calls) and provides persistence details (authenticated vs anonymous), but does not explicitly mention when not to use or alternatives among siblings.

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

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

No annotations provided; description carries burden. Discloses input formats and output fields, but lacks details on error handling, idempotency, or what happens on ambiguous input. Adequate but not comprehensive.

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, no fluff. Front-loaded with purpose and version info. Every sentence contributes meaning.

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

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

For a simple tool with two parameters and no output schema, the description covers inputs and output fields well. Could briefly mention error behavior or uniqueness, but overall complete.

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

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

Schema coverage is 100%, but description adds value by listing the three concrete input examples (ticker, CIK, name) and the output fields (including pipeworx:// URIs). Provides context beyond schema enums.

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 resolves an entity to canonical IDs across Pipeworx data sources, specifies v1 supports 'company' type, and lists input formats (ticker, CIK, name) and output fields (ticker, CIK, name, URIs). Differentiates from sibling tools by noting it replaces multiple lookup 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?

Explicitly says 'in a single call' and 'Replaces 2–3 lookup calls', guiding when to use it. No explicit when-not-to-use or alternatives, but context is clear given sibling tools are distinct.

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 details return types (verdict, structured form, citation, delta) and efficiency benefit. Does not contradict annotations. Could mention limitations but 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?

Four sentences with no wasted words; purpose, scope, return values, and efficiency all covered concisely. Front-loaded with core function.

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

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

Given one parameter and no output schema, description covers function, supported claims, and return structure adequately. Efficiency note adds context. Slightly lacks handling of ambiguous inputs 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% for the single 'claim' parameter. Description adds examples and clarifies the natural-language and supported domain, going beyond schema.

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

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

Description clearly states verb 'fact-check' and resource 'authoritative sources', specifies domain 'company-financial claims' via SEC EDGAR + XBRL, and distinguishes from siblings (none other fact-check).

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

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

Provides clear context for when to use (company-financial claims for public US companies) but lacks explicit when-not-to-use or alternative tools. Siblings don't overlap, so exclusion isn't critical.

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