Pattern detail

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), and the description layers on behavior they cannot express: the stack round-trip that include_samples controls, the fact that output is deliberately truncated (12 rows, 72 chars, top 8 services, 5 samples at 120 chars), and the projection semantics of monthly_volume_gb including the volume_actual_gb vs volume_projected_gb envelope stamp. This is real disclosure beyond structured fields.

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?

Front-loaded with the call trigger and purpose, then the payload, then the required input and routing. Most sentences earn their place, but the chart-dimension minutiae ('72 chars wide', '120 chars each') is cosmetic detail that competes with the routing information an agent actually needs.

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 explaining return contents was optional, yet the workflow routing and the must_ask_user/actions contract are exactly what an agent needs and are present. The one gap is that it asserts 'Requires pattern_hash' while the schema marks zero required parameters and offers pattern as an equivalent alias — a minor inconsistency that could mislead an agent about hard requirements.

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%, so every parameter is already documented, including the pattern/pattern_hash precedence and the projection caveat. The description restates the pattern_hash sourcing (tenx_hash from preview_filter.data.patterns[]) and little else about the remaining params (timeRange, environment, include_samples), so it sits at the baseline for a fully-covered schema.

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 ('Returns a full single-pattern view') and enumerates the concrete payload: 24h line chart, cross-service bar chart, severity breakdown, sample events. It also names its position in the workflow relative to log10x_preview_filter, so an agent can distinguish it from pattern_trend, pattern_examples, and pattern_diff without opening any schema.

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?

Explicit trigger ('CALL THIS AFTER log10x_preview_filter when the user drills into a specific pattern by number') plus named alternatives for both directions: log10x_preview_filter (back) and log10x_configure_engine (apply). It even specifies the must_ask_user prompt, so the agent knows the required interaction loop, not just when to call.

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