The Committee

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

Since no annotations are provided, the description carries the full burden of disclosure. It explains that the tool internally selects the right tool and fills arguments, and returns the result. However, it does not specify response format, error handling, or limitations (e.g., scope of data sources), which would be beneficial for an autonomous agent.

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

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

The description is concise and well-structured, with a clear first sentence stating the purpose, followed by explanation and examples. Every sentence adds value without redundancy. It is appropriately sized for a simple 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?

Given the tool's simplicity (single parameter, no output schema, no nested objects), the description is complete. It covers input format, behavior (tool selection), and provides examples. No additional context is needed for an AI agent to invoke it correctly.

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

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

With only one parameter and 100% schema coverage, the schema already documents 'question' adequately. The description adds value by clarifying that the question should be in natural language and providing examples, which goes beyond the schema's minimal description. No additional parameter details are 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 accepts plain English questions and returns answers by selecting the appropriate data source. It specifies the verb 'ask' and the resource 'Pipeworx', and distinguishes itself from sibling tools by focusing on natural language query resolution rather than tool discovery, memory, or deliberation.

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 this tool: when you want to ask a question in plain English and get an answer from the best data source. It advises against browsing tools or learning schemas, and provides concrete examples of appropriate queries. No exclusions are needed given the tool's general-purpose nature.

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 data sources (SEC EDGAR for companies, FDA for drugs) and output format (paired data with URIs). However, it does not explicitly state that it is read-only, auth requirements, or potential rate limits, leaving some gaps.

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

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

Three concise sentences, front-loaded with the core purpose, then elaborating on types and benefits. Every sentence earns its place without unnecessary verbosity.

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 complexity (two parameters, no output schema), the description covers the purpose, parameter semantics, data sources, and return format (paired data + URIs). It is sufficiently complete for an AI agent to understand and invoke correctly.

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

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

The schema covers all parameters with descriptions, and the description adds significant value by detailing what data each type returns (e.g., financial metrics for company, adverse-event counts for drug), going beyond the enum labels.

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

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

The description clearly states the tool compares 2–5 entities side by side, with specific data fields for company (revenue, net income, cash, debt) and drug (adverse events, FDA approvals, trials) types. It distinguishes itself from siblings like ask_pipeworx (Q&A) and resolve_entity (disambiguation).

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 that it replaces 8–15 sequential agent calls, indicating when to use this tool for efficiency. It does not explicitly mention when not to use or list alternatives, but the context is clear for bulk 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 are provided, so the description carries the full burden. It explains that the tool returns 'the most relevant tools with names and descriptions,' but does not disclose details like whether results are ranked, whether the search is semantic, or if there are any side effects. The behavior is generally clear but lacks deeper 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 two sentences long, front-loads the core purpose, and uses every word efficiently. 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 the tool's simplicity (2 parameters, no output schema), the description is complete enough for an agent to understand what it does and when to use it. The only minor gap is lack of return format detail, but this is acceptable for a search/discovery 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?

The input schema already covers both parameters with descriptions (100% coverage). The description adds value by reinforcing the natural language usage ('describe what you need') and providing an example query, which helps the agent understand the parameter's semantics 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 specific verb+resource: 'Search the Pipeworx tool catalog' to discover tools. It clearly distinguishes from siblings like 'ask_pipeworx' (which likely answers questions) and memory tools (forget/recall/remember). The purpose is unmistakable.

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 invocation order and context, and implicitly advises against using other tools prematurely.

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 deletion but does not disclose if deletion is permanent, requires confirmation, or affects other operations.

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 wasted words. Could be slightly improved by front-loading the key parameter.

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

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

Simple tool with one param, but no output schema and no annotations. Description lacks details on return value or side effects.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add meaning beyond schema; it just restates 'Memory key to delete'.

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 specifies the resource ('stored memory by key'). It distinguishes itself from siblings like 'recall' (read) and 'remember' (write).

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 'recall' or 'remember'. No mention of prerequisites or edge cases.

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

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

With no annotations, the description carries full burden. It discloses rate limiting (5/day) and what to include/exclude. It does not specify if feedback is processed synchronously or if confirmation is returned, but it's adequately transparent for a feedback 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?

Three sentences: purpose, specific usage guidance, and rate limit. Front-loaded with key information. 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?

The tool is simple; the description covers purpose, allowed content, and rate limits. It could mention whether a response is generated, but overall it provides sufficient context for an agent to use correctly.

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

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

The schema has 100% coverage with detailed descriptions. The description adds value by advising to describe context in terms of Pipeworx tools/data and not include user prompts, which goes beyond schema. This enriches the agent's understanding of how to use parameters.

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 verb 'Send feedback' and resource 'Pipeworx team', and lists specific use cases (bug reports, feature requests, etc.), distinguishing it from sibling tools like ask_pipeworx which are for queries.

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

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

The description explicitly says 'Use for bug reports, feature requests, missing data, or praise' and warns against including end-user prompts verbatim. It also mentions rate limits. However, it does not explicitly state when not to use or name alternatives.

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

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

With no annotations, description takes full burden. It discloses that omitting key lists all, and that memory can be from current or previous sessions. However, it doesn't mention if retrieval is read-only or has side effects, but the context implies it's safe.

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

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

Two concise sentences, front-loaded with purpose, no fluff. Every sentence adds value.

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

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

Given simple parameter structure (one optional param), no output schema, and no nested objects, description is complete enough. It explains the two modes of operation clearly.

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 both parameters fully. Description adds meaning: explains what happens when key is provided vs omitted, going beyond schema's 'description' field.

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 retrieves a memory by key or lists all memories when key is omitted. It distinguishes itself from sibling tools like 'remember' and 'forget' by focusing on retrieval.

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 to use this tool to retrieve context saved earlier, and that omitting key lists all memories. Lacks explicit when-not-to-use or alternatives, but context is clear.

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

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

No annotations provided, so description carries full burden. It discloses that memory persists for authenticated users and 24 hours for anonymous sessions, which is useful behavioral context. However, it doesn't mention any limits on key/value sizes or number of entries, which could affect behavior.

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

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

Three sentences, each adding value: purpose, use cases, and persistence detail. Front-loaded with core action. 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 no output schema and simple input schema, the description adequately covers purpose, usage, and behavioral constraints. Could mention key collision behavior (overwrite or error) for completeness, 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 description coverage is 100%, so baseline is 3. The description adds context by giving examples of keys (subject_property, target_ticker) and values (findings, addresses), but the schema already describes the parameters well. No additional semantic guidance 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 it stores a key-value pair in session memory, with specific examples of use cases (intermediate findings, user preferences, context). It distinguishes itself from siblings like 'forget' and 'recall' by explicitly focusing on 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?

The description explains when to use the tool (to save context across calls) and notes persistence differences for authenticated vs anonymous users. It does not explicitly mention when not to use it or alternatives, but context is clear.

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

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

No annotations provided, so description carries burden. Discloses output fields and input formats, but does not mention failure behavior, rate limits, or permissions. Some transparency, but gaps remain.

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: purpose, accepted formats, returned info, benefit. Every sentence earns its place. 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?

For a simple tool with 2 params and no output schema, description covers input formats, output fields, and benefit. Minor lack: no mention of error handling or future versions.

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% (type enum, value description). Description adds value by noting v1 only supports 'company', providing examples, and clarifying output. Exceeds baseline 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?

Clearly states resolve entity to canonical IDs across Pipeworx data sources in a single call, specifies types and examples. Distinguishes from siblings 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?

Implies usage by stating it accepts ticker, CIK, or name and replaces 2-3 lookup calls. No explicit when-not-to-use or alternatives mentioned among siblings.

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