get_error_count

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

With no annotations, the description carries the full burden and does disclose real behavioral quirks: trace_count counts distinct traces while observation_count counts error-level observations, and exception_count is always null because individual exception events are not retrievable via the standard observation listing. That is unusually candid disclosure of a semantic trap. It stops short of stating permissions, rate limits, or whether the window is computed from now or from the latest data.

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 first sentence is well front-loaded, but the docstring then spends lines documenting ctx (a framework-injected parameter not exposed in the schema) and restates return fields that the output schema already defines. Both are dead weight for tool selection.

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-value detail is optional, yet the description still adds the non-obvious null semantics for exception_count and the trace-vs-observation distinction, which the schema cannot convey. Given a single fully documented parameter, the definition is adequate, missing only routing guidance against 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 description coverage is 100%, so the age parameter including its 10080-minute ceiling is already documented, and the baseline is 3. The description adds only the note that the value is 'capped by the configured maximum', a runtime constraint slightly beyond the static schema bound, which is a marginal increment.

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 opening sentence names a specific verb and resource with scope: count of traces having error-level observations within a lookback window. It is clear what the tool returns, but it never contrasts itself with adjacent tools like find_exceptions or query_metrics, which a sibling-aware agent would need to choose correctly.

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?

There is no when-to-use guidance, no mention of when a count is preferable to listing exceptions via find_exceptions, and no prerequisites. The agent must infer applicability from the one-line purpose alone.

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