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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the description correctly spends its words elsewhere: it clarifies that values are computed/effective rather than raw, warns that boolean flags do not toggle supplier state, and states the auth requirement (HGRApi header channel via the internally resolved ChannelOAuthId). That is real added context rather than annotation repetition.

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 core definition is front-loaded in the first sentence, and each following sentence adds a distinct guardrail (data type, boolean caveat, auth). It is dense but mostly earns its length; the auth sentence is the weakest and could be folded into the schema note without loss.

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?

With an output schema present and annotations covering the safety profile, the remaining burden is to say what the data represents and what it is not, which the description does well. The only gap is the absence of any routing signal toward the similar source-configuration siblings.

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% and the parameter description already tells the agent to obtain the value from hgr_list_channels, so the baseline of 3 applies. The description's 'ChannelOAuthId resolved internally' slightly muddies things, since the schema marks the parameter as required and caller-supplied; a agent could plausibly read these as conflicting.

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 ('Reads effective supplier settings') and explains the 'computed' semantics: store defaults merged with supplier overrides. It also scopes the data negatively ('not supplier availability or listing usage data'). However it never names or contrasts with the close sibling hgr_get_source_configuration, so the agent must infer why both exist.

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 useful exclusion guidance ('this is settings data, not supplier availability or listing usage data') and warns that boolean monitoring settings are informational. But it offers no positive trigger for when to call this instead of hgr_get_source_configuration or hgr_get_sources, leaving the selection decision to inference.

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