Professor Sausages — Finance

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 transparently lists the data scope (SEC datasets, 10-K backfill progress, per-ticker fiscal years) and notes the tool is 'Free', which is a behavioral trait. It doesn't mention limitations or return format, but for an informational 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?

The description is concise, using a compact structure with an em dash to list the three coverage aspects. Every phrase adds value, no filler or redundancy. It is front-loaded with the core concept ('Corpus coverage') and efficiently details what it provides.

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 optional parameter, no output schema), the description is adequately complete. It covers the main functionality and the 'Free' note adds cost context. However, it could mention the return format or any typical use cases, but these are not critical for a tool of this scope.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining what the 'ticker' parameter does ('given a ticker — which fiscal years are on file for it'), reinforcing and expanding upon the schema's description. This extra context justifies a 4.

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

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

The description clearly specifies what the tool does: it provides corpus coverage information, listing specific aspects (SEC datasets, 10-K backfill progress, per-ticker fiscal years). This distinguishes it from sibling tools like find_data or pricing, which have different purposes.

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 implied usage is clear: use this tool when needing to understand what SEC data is available and for checking a ticker's coverage. However, it doesn't explicitly mention when NOT to use it or offer alternatives, so it falls short of full contextual 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, the description carries the transparency burden. It discloses the search order (server datasets first, then catalog), the return structure (method, URL, price, call instructions), and the 'Free' pricing. It does not mention potential failure modes or whether any side effects occur, but 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?

The description is two sentences: the first gives the instruction with examples, the second explains the search behavior and output. No word is wasted, and key information is front-loaded.

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 discovery tool with no output schema, the description explains what the user should provide, how the search works, and what the response will contain. This is complete for an agent to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100%, so the parameter 'task' is already documented. The description adds value by explicitly instructing users to use plain language and by providing multiple diverse examples that clarify the expected input format. This goes beyond the schema's basic description.

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

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

The description clearly states the tool's function: it searches the server's datasets and the Professor Sausages catalog to return matching endpoints with method, URL, price, and calling instructions. This verb+resource structure distinguishes it from sibling tools that provide specific data (e.g., fx_rate, ipo_calendar).

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 instructing users to describe their data needs in plain language and provides varied examples (e.g., 'Apple risk factors 2023', 'is this token a honeypot'), showing it is a discovery tool. It lacks explicit exclusions or directions to use specific sibling tools when already known, but 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 discloses the paid nature, the need for x_payment, and the exact flow. It doesn't describe return format or error behavior, but the payment mechanism is the critical non-obvious behavior and is well explained.

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 dense, relevant information. No filler. The sentence about the payment flow is necessary and well-structured, and the mention of `pricing` is directly useful.

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 or annotations, so the description must be self-sufficient. It covers the tool's purpose and the unusual payment interaction. It could mention response format or error cases, but for a narrow FX rate lookup with a well-known data source (ECB), this is adequate and reasonably 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 already describes base/quote and x_payment, but the description adds essential semantics for x_payment: it's an x402 payment payload, base64, omitting it triggers a terms request, and calling again with it settles and returns data. This goes beyond schema and is crucial for correct 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 describes a specific resource (ECB reference exchange rate for a currency pair) with an example (EUR/USD). Distinguishes itself from the sibling `pricing` tool by noting it's paid and lists a single pair, while pricing lists every price at once.

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

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

Explicitly explains the two-step payment flow: call without x_payment to get terms, sign, then call again with x_payment. Also provides an alternative: use the free `pricing` tool to list all prices at once, giving clear when-to-use 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, the description carries the full burden and discloses key behaviors: the tool is paid, requires a CIK, and follows a two-step x402 payment flow. It even specifies what the terms include ('amount, asset, network'). It stops short of describing response format or error handling, but the payment and access behaviors are well covered.

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 four sentences and each serves a purpose: purpose statement, requirement, payment workflow, and free alternative. The 'Paid:' prefix clearly separates the payment instructions. Slightly longer than the ideal two-sentence example but no wasted words enough to justify a 4.

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 (paid two-step flow) and absence of annotations/output schema, the description provides essential context: what it does, the CIK prerequisite, how to pay, and a free alternative. It doesn't detail the return structure, but for invocation purposes it's largely complete. The mention of the pricing tool adds situational context.

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% (base 3), and the description adds value by explaining the x_payment parameter's workflow: omit to receive terms, sign, then pass the signed payload. This clarifies how to use x_payment beyond the schema's basic description. The cik parameter is straightforward and benefits from the explicit prerequisite mention.

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: 'What an institutional manager bought, sold, added, and trimmed vs the prior quarter' — a specific verb+resource construction. It distinguishes itself from siblings like manager_holdings by emphasizing period-over-period changes (the 'whale-watch view'), making its 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?

Explicitly states the prerequisite ('Requires the manager's CIK') and provides a detailed usage workflow for the paid tool: call without x_payment to get terms, sign, then call again with x_payment. It also references the free pricing tool as an alternative for price listings. However, it doesn't explicitly mention when not to use this tool or contrast with manager_holdings for current holdings.

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 of behavioral disclosure. It explains the two modes (with/without ticker) and the two-step payment process (call without x_payment to receive terms, then call again with x_payment). This is strong, though it could further clarify output format or data source limitations.

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 efficient: four sentences, front-loaded with the core purpose, then expanding into usage variants and payment. Every sentence adds essential information without wordiness.

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 key contextual details: both invocation modes, the payment mechanism, and differentiation from `pricing`. Given there is no output schema, it could mention what the returned data looks like, but the description is sufficiently complete for an agent to select and invoke the tool 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?

Schema coverage is 100%: both `ticker` and `x_payment` have descriptions. The description adds some context (e.g., the exact payment flow and that ticker is optional), but largely repeats schema information. Baseline 3 is appropriate since the schema already documents parameters well.

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 identifies the tool as providing insider buy/sell activity related to SEC Form 4. It distinguishes between ticker-specific summaries and market-wide recent filings, and even contrasts with the `pricing` tool, making its purpose unambiguous and differentiated from siblings.

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

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

The description explicitly explains when to use the tool: with a ticker for company-specific data, without for market-wide filings, and details the paid payment flow. It also recommends the free `pricing` tool for price listings, effectively guiding the agent away from using this paid tool for pricing needs.

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 and excels. It discloses the paid nature, that the first call returns exact payment terms (amount, asset, network), and that a second call with the signed payload settles and returns data. This is key behavioral context beyond the schema.

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: purpose/views, payment flow, and free alternative. Front-loaded with the tool's core function, each sentence adds essential information without 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?

No output schema exists, so the description could specify return format, but it covers the essential aspects: purpose, available views, payment protocol, and alternative tool. It is sufficient for an agent to select and invoke the tool correctly, though the actual response structure is not described.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minor value by clarifying that the 'pipeline' view means 'in registration' and reinforces the view options. The x_payment explanation in the description overlaps with the schema, but the 'in registration' clarification is a useful addition.

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 provides SEC IPO pipeline data with four specific views (pipeline, priced, expected, withdrawn). It distinguishes itself from the sibling `pricing` tool by positioning itself as the pipeline-focused tool, making its purpose and scope immediately clear.

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 explains the paid nature and the two-step payment flow (call without x_payment to receive terms, sign, then call again with x_payment). It also directs users who want 'every price at once' to the free `pricing` tool, providing clear when-to-use and alternative guidance.

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

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

No annotations are provided, so the description carries the burden. It discloses the paid nature, the requirement to call without x_payment to receive terms, sign them, and call again with x_payment. This is strong transparency for a paid tool, though it doesn't mention error behaviors or return format.

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

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

Three sentences, each earning its place: resource overview, usage pattern, and payment flow. No fluff or repetition, and the most important usage guidance is front-loaded.

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 optional parameters and no output schema, the description covers the key aspects: what data is available, how to list/fetch, and how payment works. It could mention the response format or whether data is historical, but the tool is adequately specifiable as-is.

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 both parameters have descriptions. The description adds value by explaining the payment sequence associated with x_payment and the optionality of id, complementing the schema's 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 identifies the resource (US macroeconomic series) and the actions: pass an id to get one series or omit to list available ones. It differentiates from sibling tools by naming the free `pricing` tool for all prices at once.

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

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

Explicitly explains when to use the tool: pass an id for a specific series, omit to list. It also provides a clear alternative ('The free `pricing` tool lists every price at once') and details the two-step payment flow, which is crucial for correct 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?

No annotations are provided, so the description must carry the full burden. It discloses the critical behavioral trait: this is a paid tool requiring a two-step payment process. It also clarifies search behavior for name fragments. It does not mention rate limits or output details, but the core non-obvious behavior (payment flow) is well explained.

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: main purpose first, then usage examples, then payment instructions, then an alternative tool. Every sentence contributes useful information without 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 complexity (paid, two-step, search) and lack of output schema, the description covers the key invocation details, payment flow, and alternative pricing tool. It does not describe the exact return format, but holdings data is implied and not critical for invocation. Overall it provides sufficient context for correct 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%, so the schema already documents both parameters. The description adds value by explaining that 'manager' accepts a CIK or a name fragment for searching, and clarifies that 'x_payment' is an optional signed payload with a specific purpose (settle payment after receiving terms). Examples further reinforce semantics.

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 returns an institutional manager's 13F holdings for the latest quarter, with a specific verb ('Pass a CIK') and resource. It distinguishes itself from siblings by focusing on manager-level portfolio holdings and explicitly contrasts with the 'pricing' tool for price data.

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

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

Provides explicit usage instructions: pass a CIK or name fragment to search, and explains the paid two-step flow (omit x_payment to get terms, then call again with signed payload). It also directs users to the free 'pricing' tool for prices, giving a clear alternative. However, it doesn't explicitly distinguish when to use this vs. 'holdings_changes' or other 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?

With no annotations, the description carries the burden. It discloses that data is read live from the route table and that the call is free, but it doesn't address authentication, rate limits, or response format beyond a one-line summary.

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 sentence that front-loads the essential information: scope, content, and cost.

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 no-param tool without an output schema, the description covers the key aspects: what it returns, that it's live, and that it's free. Minor gaps exist, such as response structure, but overall it is sufficient.

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 tool has zero parameters, so the description needn't explain parameter semantics. The baseline of 4 applies, as there is no gap to compensate for.

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

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

The description clearly states that it lists every endpoint with its exact per-call USD price and a one-line summary, making the tool's purpose unambiguous and distinct from sibling data 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?

Usage is implied as a reference for endpoint pricing, but the description does not explicitly say when to use it (e.g., before calling any endpoint) or contrast it with 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, the description carries the burden and does it well: it reveals that requests feed a nightly ingestion queue, filings usually appear within ~24 hours, contact is optional for follow-up, and the service is free. This goes beyond a basic mutation request and sets expectations about asynchronous processing.

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 punchy sentences: the first explains what the tool is and gives examples, the second covers queue timing, contact, and cost. Every word earns its place, with no fluff or repetition.

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 request tool with no output schema and one required parameter, this description is well-rounded. It covers the purpose, process, timing, contact, and pricing. It does not explain the full request lifecycle (e.g., whether requests are public) but given the simplicity, this is not a major gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a little context around the contact parameter ('include contact if you want to hear back') but does not explain the description or use_case parameters beyond what the schema already provides. It neither improves nor worsens schema clarity.

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 identifies the tool as a 'suggestion box' for requesting missing data, with concrete examples (pre-2015 filing, uncovered ticker, unsupported chain, whole dataset). This specific verb+resource framing distinguishes it from the sibling data-retrieval tools like find_data and coverage.

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

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

The description implies usage when data is not already available ('ask for data we don't have') and gives examples that reflect gaps. It does not explicitly name sibling tools as alternatives, but the context of 'missing data' and the queue behavior make the intended use clear. Slightly stronger if it said 'instead of find_data, use this'.

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 of disclosing behavior. It discloses the paid nature, the payment negotiation flow, the corpus date range (2015→now), and the default form. It doesn't mention error handling or rate limits but covers the most important behavioral trait (payment) well.

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 four sentences, front-loaded with the core purpose, then an example, corpus info, and payment instructions. Every sentence earns its place 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 tool with 5 parameters and no output schema, the description covers the essential context: forms, default, sections, corpus range, missing-filing alternative, and the paid payment flow. It doesn't explain the 'manifest' concept or return structure, but the intended usage is clear enough.

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 includes an example combining ticker, selector, and sections, but this largely repeats schema examples. The x_payment flow is also described in the schema, so the description adds little beyond what the schema already 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 the tool provides 'Parsed sections of a SEC filing by ticker or CIK: 10-K (default), 10-Q, or 8-K.' It names specific section types and the input key. It also distinguishes from siblings by noting missing filings go to request_data and pricing is handled by the free pricing tool.

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 'missing filings can be requested via request_data' and 'The free `pricing` tool lists every price at once,' providing when-not-to-use alternatives. It also explains the paid flow: call without x_payment to get terms, then call again with x_payment. This is clear guidance on usage and 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, the description carries the full burden. It discloses that this is a paid tool requiring a two-step payment process (obtain terms, sign, resubmit) and mentions the free pricing alternative. This is critical behavioral context. It does not mention rate limits or failure modes, but for a simple 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, then payment instructions, and a pointer to a free alternative. Every sentence 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?

The tool has no output schema, so the description should hint at return values—it does ('who owns it, position sizes, and changes'). It also explains the payment workflow thoroughly. It could more explicitly state that the second call returns the data, but the implication is clear. Overall complete for the tool's 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%: both cusip and x_payment are documented in the schema. The description reiterates the payment flow but adds no new parameter semantics beyond what the schema already explains (e.g., the x_payment base64 payload and the two-step process). 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 the tool provides institutional holders of a security by CUSIP, including who owns it, position sizes, and changes. This distinguishes it from siblings like manager_holdings (likely about a manager's holdings) and holdings_changes (likely about changes). The title 'Who holds a security (13F)' reinforces the purpose.

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 the payment workflow (call without x_payment to get terms, sign, call again with x_payment) and points to the free pricing tool as an alternative for pricing. However, it does not explicitly differentiate when to use security_holders versus holdings_changes or manager_holdings, though the purpose is clear enough to infer.

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