sec

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

With no annotations provided, the description carries the full burden and effectively discloses key behavioral traits: it describes the tool's process ('Pipeworx picks the right tool, fills the arguments, and returns the result'), input format ('plain English'), and scope ('best available data source'). However, it lacks details on limitations such as rate limits or error handling.

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 appropriately sized and front-loaded, with every sentence earning its place: the first sentence states the core functionality, the second explains the process, the third provides usage guidance, and the fourth gives concrete examples. There is no redundant or wasted 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 complexity (natural language processing with backend tool selection) and lack of annotations or output schema, the description is mostly complete: it covers purpose, usage, and process. However, it does not detail output format or potential limitations, leaving some gaps for an AI agent to infer behavior.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds value by explaining the parameter's semantics beyond the schema: it specifies that the question should be in 'plain English' or 'natural language', provides examples of valid inputs, and contextualizes it as a descriptive request rather than a structured query.

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 with specific verbs ('Ask a question', 'get an answer') and resources ('best available data source'), distinguishing it from siblings by emphasizing natural language interaction versus structured queries. It explicitly contrasts with sibling tools like get_company_facts or search_companies by noting 'No need to browse tools or learn schemas'.

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

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

The description provides explicit guidance on when to use this tool ('just describe what you need' in plain English) and when not to use it (versus browsing tools or learning schemas), with clear alternatives implied by the sibling tools listed. Examples like 'What is the US trade deficit with China?' illustrate appropriate use cases.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the tool returns 'the most relevant tools with names and descriptions,' which gives some insight into output behavior, but lacks details on aspects like error handling, performance, or rate limits. The description adds value by specifying the tool's role in a large catalog context, but more behavioral traits could be disclosed.

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 front-loaded and efficiently structured in two sentences: the first states the purpose and outcome, and the second provides clear usage guidelines. Every sentence adds essential value without redundancy, making it appropriately concise and well-organized for quick understanding.

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 (a search function with 2 parameters) and the absence of annotations and output schema, the description is reasonably complete. It covers the tool's purpose, usage context, and high-level behavior, but could benefit from more details on output format or error cases. However, it effectively addresses the core needs for a discovery tool in a large catalog.

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 both parameters (query and limit) thoroughly. The description does not add any parameter-specific information beyond what the schema provides, such as examples or usage nuances. With high schema coverage, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

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 with specific verbs ('Search the Pipeworx tool catalog') and resources ('tool catalog'), explicitly distinguishing it from sibling tools like get_company_facts or search_companies by focusing on tool discovery rather than company data. It specifies the action (search by describing needs) and outcome (returns relevant tools with names and descriptions).

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

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

The description provides explicit guidance on when to use this tool: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This includes a clear condition (500+ tools) and a specific recommendation (call first), effectively distinguishing it from alternatives by positioning it as an entry point for tool discovery.

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 of behavioral disclosure. It states this is a deletion operation, implying it's destructive, but doesn't specify whether the deletion is permanent, reversible, requires specific permissions, or has side effects. For a destructive tool with zero annotation coverage, this is insufficient.

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, clear sentence with zero wasted words. It's front-loaded with the core action and resource, making it highly efficient and easy to parse.

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 destructive tool with no annotations and no output schema, the description is inadequate. It doesn't explain what 'stored memory' entails, how deletion affects the system, what happens on success/failure, or return values. Given the complexity and lack of structured data, more context is needed.

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

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

Schema description coverage is 100%, with the single parameter 'key' documented as 'Memory key to delete'. The description adds no additional meaning beyond this, such as key format or examples. Since the schema does the heavy lifting, the baseline score of 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 clearly states the action ('Delete') and resource ('a stored memory by key'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'recall' or 'remember', which appear related to memory operations, so it doesn't fully distinguish itself from alternatives.

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 no guidance on when to use this tool versus alternatives like 'recall' or 'remember', nor does it mention prerequisites or exclusions. It simply states what the tool does without contextual usage information.

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 of behavioral disclosure. It describes the tool as a read operation ('Get') and specifies the return data, but does not disclose important behavioral traits such as rate limits, authentication requirements, error handling, or data freshness. For a tool with no annotations, this leaves significant gaps in understanding how it behaves in practice.

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 front-loaded with the core purpose in the first sentence and efficiently adds details about the return data in the second. It avoids unnecessary words and stays focused on the tool's functionality. However, it could be slightly more structured by explicitly separating usage guidelines or behavioral notes, but overall it is concise 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 tool's complexity (single parameter, no output schema, no annotations), the description adequately covers the purpose and return data. However, it lacks details on behavioral aspects like error handling or data scope, and without an output schema, it does not fully explain the structure of returned values. It is minimally viable but has clear gaps in providing a complete context for effective 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 100% description coverage, with the single parameter 'cik' fully documented in the schema. The description adds minimal value beyond the schema by reiterating the use of CIK but does not provide additional context like format examples or edge cases. Since schema coverage is high, the baseline score of 3 is appropriate, as the description does not significantly enhance parameter 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 specific action ('Get XBRL financial facts') and resource ('for a company using its CIK number'), distinguishing it from sibling tools like 'get_company_filings' and 'search_companies' by focusing on financial data extraction rather than filings or search. It explicitly mentions the type of data returned ('structured financial data including revenue, net income, total assets, and other reported metrics over time'), making the purpose highly specific and well-defined.

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

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

The description implies usage by stating it retrieves financial facts for a company using a CIK number, which suggests it should be used when detailed financial metrics are needed. However, it does not explicitly state when to use this tool versus alternatives like 'get_company_filings' or 'search_companies', nor does it provide exclusions or prerequisites. The guidance is present but lacks explicit comparison or context for tool selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes what the tool returns (filing dates, form types, accession numbers) and mentions optional filtering, which adds useful context. However, it lacks details on rate limits, authentication needs, or pagination behavior, leaving gaps for a mutation-free read operation.

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 appropriately sized and front-loaded, with two concise sentences that efficiently convey the tool's purpose and key features. Every sentence earns its place by adding specific information without redundancy.

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

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

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is mostly complete. It covers the purpose, usage, and return values adequately. However, the lack of output schema means it could benefit from more detail on response structure or error handling, slightly reducing completeness.

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 description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds minimal value by reiterating the optional filtering and providing examples (e.g., '10-K'), but does not significantly enhance the parameter semantics beyond what the schema provides, meeting 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 the tool's purpose with specific verb ('Get') and resource ('SEC filings for a company'), and distinguishes it from siblings by specifying it retrieves filings rather than facts (get_company_facts) or company searches (search_companies). The mention of CIK number and filtering by form type adds specificity.

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

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

The description provides clear context for when to use this tool (to get SEC filings for a company using CIK), and it implies an alternative by mentioning optional filtering by form type. However, it does not explicitly state when not to use it or name specific sibling alternatives, which prevents a score of 5.

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 explains the dual behavior (retrieve by key or list all) and mentions persistence across sessions, which is valuable context. However, it doesn't disclose important behavioral traits like error handling (what happens if key doesn't exist), format of returned memories, or any rate limits/authentication needs.

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 perfectly concise with two sentences that each earn their place. The first sentence explains the core functionality, and the second provides usage context. No wasted words, and information is front-loaded appropriately.

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

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

For a tool with no annotations and no output schema, the description does an adequate job explaining what the tool does and when to use it. However, it lacks information about return format, error conditions, and persistence details that would be helpful given the absence of structured output documentation.

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

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

With 100% schema description coverage and only one optional parameter, the description adds significant value beyond the schema. It explains the semantic meaning of omitting the key parameter ('omit to list all keys') and clarifies that keys are used to retrieve 'context you saved earlier,' giving purpose to the parameter that the schema alone doesn't provide.

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 with specific verbs ('retrieve', 'list') and resources ('previously stored memory by key', 'all stored memories'). It distinguishes from siblings like 'remember' (store) and 'forget' (delete) by focusing on retrieval 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 explicit guidance on when to use this tool: 'to retrieve context you saved earlier in the session or in previous sessions.' It also specifies when to omit the key parameter to list all memories, giving clear usage instructions.

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 and adds valuable behavioral context beyond the basic storage function. It discloses that authenticated users get persistent memory while anonymous sessions last 24 hours, which informs about persistence and session handling. However, it does not mention potential limitations like storage size 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 appropriately sized and front-loaded, with the first sentence stating the core purpose and subsequent sentences adding essential context without waste. Every sentence earns its place by clarifying usage and behavioral details efficiently.

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 (2 parameters, no output schema, no annotations), the description is mostly complete. It covers purpose, usage, and key behavioral traits (persistence differences). However, it lacks details on return values or error handling, which could be helpful for a storage tool without an 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?

The schema description coverage is 100%, so the schema already documents both parameters ('key' and 'value') with examples. The description does not add significant meaning beyond what the schema provides, such as explaining parameter interactions or constraints, meeting the baseline for high schema coverage.

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 ('Store') and resource ('key-value pair in your session memory'), making the purpose specific and actionable. It distinguishes from sibling tools like 'recall' (which likely retrieves) and 'forget' (which likely deletes) by focusing on storage rather than retrieval or deletion.

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

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

The description provides clear context for when to use this tool ('save intermediate findings, user preferences, or context across tool calls'), which helps guide the agent. However, it does not explicitly state when not to use it or name alternatives (e.g., when to use 'recall' instead), missing full explicit guidance.

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

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

With no annotations provided, the description carries full burden. It discloses the search behavior and that it returns 'matching company names and their CIK numbers', but lacks details on rate limits, authentication needs, result limits, or error conditions that would be helpful for a search 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?

Two sentences with zero waste: the first states purpose and parameters, the second explains the return value and its downstream use. Every element serves a clear purpose in helping the agent understand and use the 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?

For a single-parameter search tool with no annotations and no output schema, the description provides adequate context about what it does and why the output matters. It could be more complete by mentioning result format or limitations, but covers the essentials given the tool's relative simplicity.

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

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

Schema description coverage is 100%, so the schema already documents the single 'query' parameter thoroughly. The description adds minimal value beyond the schema by mentioning 'name or ticker symbol' and the example format, which is already covered in the schema description.

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

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

The description clearly states the specific action ('Search SEC EDGAR'), resource ('companies'), and method ('by name or ticker symbol'), distinguishing it from siblings like get_company_facts and get_company_filings which likely retrieve different data types rather than performing searches.

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

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

It provides clear context for when to use this tool ('Search SEC EDGAR for companies by name or ticker symbol') and mentions the output's purpose ('CIK numbers, which are needed for other SEC tools'), but doesn't explicitly state when not to use it or name specific alternatives among the sibling tools.

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