layout_assistant

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

With no annotations provided, the description must carry transparent behavioral info. It discloses the fix mechanism (execute_batch), notes units are points, and implies diagnose/preview are non-destructive while fix is a mutation. However, it omits side effects (e.g., whether it modifies the document directly, undo behavior, or any requirements like needing an open document) and doesn't describe the output of the diagnose/preview modes, leaving gaps for an agent to infer.

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, each purposeful: the first states the core purpose, the second lists the modes, and the third provides workflow and unit context. It front-loads the most important information and contains no wasted words, achieving high information density in a compact text.

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 tool with 8 parameters, no output schema, and no annotations, the description covers the core purpose, modes, and workflow but leaves significant gaps. It doesn't explain what diagnose/preview return (e.g., a list of issues, a plan), what the plan structure looks like, or what the effects of fix are beyond 'execute_batch'. The lack of an output schema makes these omissions more impactful, so while the description is adequate for a common case, it's incomplete for an agent to fully anticipate the tool's behavior.

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?

The schema already documents 7 of 8 parameters (88% coverage), so the baseline is 3. The description adds meaningful value by stating 'Units are points' (clarifying marginPt and minGapPt) and by mentioning the relationship between fix and execute_batch, which provides context for the mode parameter. It doesn't describe every parameter, but the additional unit context justifies a 4, slightly above 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 opens with a specific action ('Diagnose or fix') and a clear resource ('page layout') with concrete problem types ('overlapping/tight text, items outside margins'). It enumerates the three modes, which immediately distinguishes the tool from sibling tools like scan_document (which scans) and analyze_page (analyzes). The explicit mode list and mention of execute_batch clearly differentiate its role.

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?

It provides explicit sequencing guidance ('Prefer after scan_document (+ analyze_page for title roles)'), which tells the agent when in a workflow it should be invoked. It also clarifies that fix applies via execute_batch, implying a batched operation. However, it doesn't explicitly name alternatives or explain when not to use this tool, so it's not a 5.

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