dynatrace_managed_list_available_metrics

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

Annotations already declare readOnlyHint=true, and this description aligns with that. The description adds value by stating that results include aggregation types, dimension definitions, and technical metadata — useful behavioral context beyond the read-only flag. However, it does not mention pagination behavior or the possibility of a large result set beyond the limit parameter.

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?

One clean sentence that states the primary action, scope, optional filter, and result contents. Efficient and front-loaded with the verb and resource. No wasted words.

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 read-only listing tool with 100% schema coverage and detailed parameter descriptions, the definition is mostly complete. It could mention that the output is a list of metric definitions rather than values, but the description's mention of technical metadata already hints at that. Given the absence of an output schema, a slightly clearer statement of the return shape would help, but overall it is adequate.

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%, so the baseline is 3. The description adds a bit about the overall output contents (aggregation types, dimensions, metadata) but does not materially enrich the individual parameter semantics beyond what the schema already provides. The parameter descriptions are already detailed and self-sufficient, so this is slightly above baseline.

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 clearly states the tool lists available metrics in the Managed cluster with optional entity filtering, and specifies that results include aggregation types, dimension definitions, and technical metadata. The verb 'List' plus the resource 'available metrics' distinguishes it well from sibling tools like query_metrics_data, get_metric_details, and list_entity_types.

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 implies when to use it: when the user wants to discover available metrics, optionally filtered by entity, rather than querying metric data or getting details of a single metric. It does not explicitly name alternatives or state exclusions, but the sibling names and tool name make the context reasonably clear.

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