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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses meaningful behavior: a ~1-week publication lag, as_of_date defaulting to the latest available rather than today, cusip overriding view, and holding_type narrowing only within treasury or agency modes. These details materially change how an agent interprets results and are not inferable from annotations or schema alone.

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 dense but each sentence earns its place: core subject, default summary behavior, treasury/agency snapshot behavior, CUSIP lookup override, and publication lag. The most broadly relevant usage is front-loaded, and the CUSIP override is stated independently to avoid ambiguity.

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 (three views, a CUSIP override, view-specific holding types, and a non-obvious default date), the description covers all calling patterns and defaults an agent needs. It even provides the key phrase for when to use the summary view. The absence of an output schema is offset by the clear behavioral and selection guidance.

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 already 100%, but the description adds selection semantics beyond the schema: it explains how view, cusip, as_of_date, and holding_type interact, clarifies the default for as_of_date, and maps holding_type values to each view. It does not add much for limit, which is already self-explanatory, but the added parameter context is genuine and valuable.

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 names a specific resource (the Fed's SOMA securities holdings) and a clear set of verbs/views: summarize holdings, retrieve treasury/agency snapshots, or look up a CUSIP's history. It also orients the agent by noting this is 'the series to read for SOMA runoff this month', which differentiates it from sibling Fed tools like nyfed_repo_operations or nyfed_primary_dealer_stats.

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 strong mode-based guidance: view=summary for totals over time, view=treasury/agency with as_of_date for CUSIP-level snapshots, and cusip alone for security history regardless of view. It gives clear context and implicit exclusions (e.g., don't pass cusip with view expecting a summary), though it does not explicitly name when-not-to-use sibling tools.

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