engine_html_save

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

No annotations are provided, so the description carries the burden. It discloses that the file travels 'byte for byte' and that the body comes either as content or as a file path, which is useful. However, it doesn't disclose whether the save overwrites existing content, whether it requires specific permissions, or what happens if both content and file are provided. The 'build' parameter behavior is explained, but the core mutation behavior is not fully transparent.

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 compact and front-loaded with the core action ('Save an existing template view .htm'). The second sentence efficiently explains the body source alternatives. The 'build' parameter description is embedded in the schema rather than the main description, which is acceptable. No wasted words, though the phrasing 'Say it only when...' is slightly awkward.

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 save/mutation tool with no annotations and no output schema, the description covers the main input modes and the 'build' flag's purpose. However, it lacks details about overwrite behavior, error conditions, whether the template must already exist, and what the return value is. Given the sibling set includes many similar save/add tools, more context about how this differs from engine_static_save or engine_template_add would help.

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 50%: 'file' and 'build' have descriptions, but 'path' and 'content' do not. The description adds meaning by explaining that 'content' and 'file' are alternative body sources and that 'file' is a path on this machine. It also clarifies the 'build' parameter's purpose. However, it doesn't explain the 'path' parameter beyond the schema, and the relationship between 'path' and 'file' could be clearer.

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 verb ('Save') and resource ('an existing template view .htm'), and clarifies the two ways the body can be supplied (content or file). It distinguishes from siblings like engine_html_add (which likely creates) and engine_html_load (which reads), though it doesn't name them explicitly.

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 implies usage context: it saves an existing template view, and the 'build' parameter description explains when to set it (only when the same save should make visitors take fresh styles). However, it doesn't explicitly state when to use this tool versus alternatives like engine_html_add or engine_static_save, nor does it mention prerequisites like the template view needing to exist.

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