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

readOnlyHint=true already tells the agent this is a safe read, and the description adds useful sequencing (search first, then get_document) and the datasetId value used for text search. It says nothing about result shape, pagination via limit (max 100), or the unsupported_capability behavior tied to asOf, which the schema mentions but the description does not surface.

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 tight sentences, front-loaded with what the tool searches and followed by the routing rules; no filler. The form-code list is slightly dense but earns its place as valid filter values.

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 7-parameter, zero-required search tool with no output schema, the description covers the essential decisions: which corpus, which form types, and when to switch into full-text mode ahead of get_document. Gaps remain around time filtering (timeRange/asOf semantics) and what a result row actually contains beyond an implied document reference.

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 57%, and the description adds real meaning for datasetId (concrete registered ids including sec.full_text_search) and documentTypes (the SEC form codes), plus implies entity via 'without a specific company'. However, asOf, limit, and the nested timeRange receive no explanation in the description, and limit/timeRange have no schema descriptions either.

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?

States a specific verb and resource ('Search public research documents'), the initial corpus (SEC EDGAR filings), and enumerates the document types covered. It also carves out a distinct mode (datasetId sec.full_text_search with query) so an agent can tell what this tool retrieves without opening the schema.

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 routes the agent: use this to locate filings 'before calling get_document', and use sec.full_text_search with query when there is no specific company. That gives a clear when-to-use and a conditional variant, but it never mentions the sibling search_data_catalog (the apparent source of registered datasetIds) or any when-not-to-use case.

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