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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is safe to call repeatedly. The description adds the 'empty search with no filters returns the full catalog' behavior, which is helpful context for expected output volume. It doesn't describe pagination or size limits, but for a catalog lookup tool the annotations cover the safety profile; 3 reflects the modest additional disclosure.

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 with no filler: the first states the verb and scope, the second names the sibling tools and the reverse-lookup use, the third notes empty-search behavior. Slight room for improvement: the sentence about 'Usability' could be trimmed, but it's information-dense and front-loaded. Loses a point for slight denseness but not for waste.

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 an output schema exists (return format is documented separately), the description covers the key use case: discovering friendly names before calling get_financials or fetch_frames. It explains the search mechanisms and empty behavior. Missing pagination/limit details are minor for a search catalog tool with an output schema; 4 reflects adequate completeness with a small 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 schema already documents all three parameters, including enums with per-item explanations (e.g., balance_sheet covering position items with instant periods). The description adds the reverse-lookup example ('NetIncomeLoss' maps to net_income) which clarifies search semantics beyond the schema's substring description. This adds value but doesn't need to carry the full parameter burden; 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?

States a specific verb+resource purpose: search XBRL financial concepts by keyword, statement group, or taxonomy. Clearly distinguishes itself from siblings by naming two specific consumers (secedgar_get_financials, secedgar_fetch_frames). Goes beyond a generic greeting to explain what the search returns and the reverse-lookup capability.

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 when-to-use guidance: 'Use before secedgar_get_financials or secedgar_fetch_frames to discover the right friendly name'. This positions it as a discovery prerequisite relative to its likely siblings. Confirms the empty-search behavior (returns full catalog) without exclusions. The when-not scenario isn't stated, but the positive guidance is specific and directional.

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