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

Beyond the readOnly annotations, the description discloses list-mode details such as caveat_count, broken_reason semantics, proposed_for_removal marks, inclusion of older review definitions, and truncation signals. Read mode similarly explains what is returned, including formula representation, object.field grounding, caveats, and recorded values when tracking is enabled.

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?

It is front-loaded with the primary purpose and every sentence carries substantive behavioral information. The definition is dense and somewhat lengthy, but there is little wasted text and the structure moves logically from list mode to read mode to usage guidance and truncation.

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 no output schema, the description supplies the necessary return-shape context for both modes, including caveat, broken-state, truncation, formula, grounding, and recorded-value details. No critical information needed to call the tool correctly appears to be missing.

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 100% and already documents name as 'the metric to read, as the list spells it' and that omitting it lists every metric. The description reinforces the dual list/read behavior but does not add syntax or format detail beyond what the schema provides, so the baseline of 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?

The description opens with a precise verb and resource: 'Read one metric in full, or list every metric defined for this workspace.' It distinguishes both operating modes and explicitly routes the agent away from the sibling tool fetch, so the tool's role is unmistakable.

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 states exactly when each mode applies: omit name to list metrics, supply name to read one. It also gives cross-tool guidance by naming configure_metric for starting tracking and fetch as the alternative when the client cannot call this tool, plus the caveat to read caveats before citing numbers.

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