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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: the mandatory actions_details pre-step and the exact filtering semantics of the accounts mode (no filter = all sources, platform = that platform, workspace/brand = scoped subset). It says nothing about pagination, result size, or caching.

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 stepwise bullet layout is well suited to a multi-mode workflow tool and the ordering constraint appears early. There is mild redundancy between the opening sentence and the step list, and the brands step is buried at the end as an afterthought, but nothing is wasted enough to hurt.

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?

An output schema exists, so return-shape explanation is not required, and the description covers the mode selection, prerequisite ordering, and filter behavior that an agent needs to call it correctly. Remaining omissions (error behavior, action identifier format) are minor for a read-only metadata helper.

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 0%, so the description carries the full burden and mostly does: it names each request enum value and explains how platform, workspace_id, and brand_id narrow the accounts result. Gaps remain for the actions parameter (string vs array accepted) and for what the brands mode does when brand_id/workspace_id are omitted.

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 frames the tool as a discovery/metadata helper and then enumerates the four request modes (accounts, available_actions, actions_details, brands), so an agent can tell it retrieves query context rather than executing queries. It does not explicitly contrast itself with query_data or execute_action, so the boundary with siblings is implied rather than stated.

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?

Numbered steps give an explicit ordering: accounts first, then available_actions, then actions_details, which is flagged as REQUIRED before querying. It also points to list_platforms for platform discovery. What's missing is a when-not clause, e.g. that this tool returns no data rows and query_data should be used for actual retrieval.

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