create_layout

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

With no annotations, the description carries the full burden of behavioral disclosure. It states that the tool creates a layout in the project and that a map frame is already included, which are meaningful side effects beyond the tool name. It also clarifies the 'empty map_name uses active map' behavior. It could mention whether the project needs to be saved separately, but for a creation tool with an output schema, the disclosed behavior is adequate.

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 opens with a clear one-sentence purpose, adds a single high-value workflow note about export_layout, then lists all arguments compactly. There is no filler, redundant restatement, or unnecessary detail. Every sentence earns its place.

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 six optional parameters and an output schema, this description is complete: it explains the tool's role, all parameter semantics with defaults, allowed unit values, and the natural next step of exporting. Since an output schema is present, omitting return-value details is acceptable. No critical information needed to invoke the tool correctly is missing.

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 fully, and it does. Every parameter is given semantic meaning: name is the layout name, map_name selects the map and falls back to the active map, width/height define page size, units lists all allowed values, and margin is explained as the frame margin from the page edge in page units. This goes far beyond the schema's bare titles and defaults.

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 states a specific action and resource: 'Create a new layout in the project with a map frame already added.' This clearly distinguishes it from siblings like create_map (which creates a map, not a layout) and export_layout (which exports rather than creates). The added detail about the map frame prevents confusion with other layout-related tools.

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 provides clear workflow context by instructing the agent to 'call export_layout()' after creation. This tells the agent how this tool fits into a larger sequence and implicitly routes export tasks to export_layout. It does not explicitly mention when not to use it versus create_map or list_layouts, but the workflow guidance is clear and actionable.

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