failure_analysis

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

With no annotations, the description must disclose all behavioral traits. It states the tool 'uploads failure data CSV, identifies top failure modes, correlates with lots, and provides recommendations,' but does not mention side effects (e.g., data mutation, authentication needs) or whether it modifies any state. The phrase 'actionable recommendations' hints at non-destructive analysis, but it is insufficiently explicit.

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 three sentences plus an IMPORTANT note, all front-loaded with the title-like first line. Every sentence earns its place, and there is no extraneous information. It is efficient and clear.

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?

The description covers the main functionality (Pareto analysis, lot correlation, recommendations) and includes a usage note. Given that an output schema exists (context confirms), the description need not detail return values. It is complete enough for a analysis tool, though it could briefly mention the output format (chart/report).

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% for the single parameter 'failure_data_path,' and the tool description adds no extra meaning beyond restating that it uploads a CSV. The schema already documents the expected columns. Thus, the description provides marginal added value, meeting the 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 'Run Pareto analysis on failure data with lot correlation,' specifying a specific verb and resource. It differentiates from siblings like quality_fai_inspect and test_coverage_analysis by naming the analysis type and referring to 'Station 5,' indicating a unique process step.

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 includes 'IMPORTANT: Review Pareto chart and lot correlation before taking action,' which implies the tool is for analysis only and should be reviewed before further actions. However, it does not specify when to use this tool versus alternatives or provide exclusions.

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