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

With readOnlyHint, idempotentHint, and destructiveHint already declared, the description correctly adds operational context beyond annotations: large filers can have 3,000+ positions, pagination is indicated by _has_more, and no API key is required. It does not contradict the annotations and adds useful scale and pagination behavior, though it could say more about rate limits or failure modes.

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 well-structured, with purpose first, then workflow, then parameter guidance. However, it spends a long block enumerating return fields even though the tool has an output schema, making that section largely duplicative and reducing conciseness.

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 complexity of a filing-parsing tool, the description covers the essential workflow, filters, sorting, pagination, and data source. Because an output schema exists, it does not need to fully explain return values, so the remaining omission is mainly that unrelated-looking parameters are left unaddressed.

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 description adds useful meaning for key parameters such as min_value_thousands, sort_by, limit, and offset. However, several schema parameters (mcp_prompt_id, question_asked, wholesaler_ids, exclude_fillers, source_resource_id, additional_display_fields, optional_additional_filters) are entirely unexplained in the description, which is a notable gap given the reported low schema description 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 states a specific verb-and-resource pair ('fetch and parse the complete equity holdings table') scoped to a specific SEC 13F-HR filing. It also distinguishes this tool from the sibling discovery tools by framing itself as 'Step 2' after SearchEdgar13F or GetEdgarCompanyFilings, which removes ambiguity about which tool retrieves filings versus positions.

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 gives an explicit workflow: obtain cik and accession_no from SearchEdgar13F or GetEdgarCompanyFilings, then call this tool. It also names concrete parameter usage rules (min_value_thousands to filter noise, sort_by='value_desc' to prioritize large positions, limit/offset with _has_more for pagination), which is more than enough for correct invocation.

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