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

Beyond the annotations, the description discloses several important behaviors: recursion defaults to true and can be disabled, pricing is computed from the returned slice fact count, and a 404 still costs 10 credits. It also explains that slice facts are grouped by XBRL axes. This adds significant context beyond the readOnly/idempotent hints.

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 information-dense and front-loaded with the core behavior, then scope, recursion, pricing, and error semantics. The endpoint and documentation reference at the end are slightly redundant, but nearly every clause adds useful operational detail.

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 the key call-time decisions: scope, recursion, pricing, and the 404 case. Since there is no output schema, the description explains the return shape at a conceptual level (consolidated fact plus grouped slice facts) but does not detail the response fields. This is sufficient for correct invocation.

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 every parameter. The description restates the filing_id-vs-ticker scoping and recursive default, but it does not add meaningful new detail about parameter formats, allowed values, or relationships beyond what the schema provides. 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?

The description names the specific verb and resource: it returns one consolidated fact plus every slice fact it breaks down into. It also clarifies the grouping principle (by XBRL axes) and the fact_id-based scope, which separates it from the sibling get_dimensional_breakdown_by_line_item.

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 gives clear context for invoking the tool: it specifies the two valid scoping forms (filing_id OR ticker + fiscal_year), optional quarter, and the recursive flag with its default. It does not explicitly name alternatives or state when not to use this tool, so it falls short of a 5.

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