metrics_metric_increment

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

Since no annotations are provided, the description must disclose all behavioral traits. It states that the counter is created if missing and returns updated state. However, it does not mention idempotency, atomicity, or concurrency behavior. A score of 3 is adequate given the basic disclosure but missing details.

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 description is relatively short (four sentences) and front-loaded with the core action. It includes some extra detail about tracked fields, which may or may not be necessary, but overall is efficient.

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 (implied) and no annotations, the description covers the essential behavior (increment, create if missing, return state). However, it does not explain the 'tags' parameter or relate the tool to siblings like metric_gauge. Some gaps remain.

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 must compensate. It explains the 'value' parameter (optional, defaults to 1) and implies 'name' is the metric name, but 'tags' is not mentioned at all. This partial coverage leaves a gap.

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?

Description clearly states it increments a counter metric by a value, and creates the counter if it doesn't exist. The verb 'increment' and resource 'counter metric' are specific. While it doesn't explicitly distinguish from siblings like metric_gauge, the action is unique and immediately understandable.

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?

No guidance on when to use this tool versus alternatives like metric_gauge (for gauges) or metric_get (for reading). The description implies use for incrementing but does not address when not to use or provide comparisons to siblings.

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