write_meta

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

With no annotations supplied, the description carries the full burden, and it does disclose the key trait: this is a destructive full overwrite, not an append, which is why it demands a read-append-write cycle. It does not mention required permissions, whether content is validated before writing, or any recovery path despite siblings like undo_last_vault_change existing.

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?

Four lines, front-loaded with the core action, then the enumerated targets, then the one workflow that needs explanation. No sentence is filler and no repetition of the schema.

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 return values need not be described, and for a two-parameter tool the description covers target values, overwrite semantics, and the correct pre-write sequence. The remaining gap is that the content shape for tag-dictionary and foreign-definitions is never described, leaving those two code paths underspecified.

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% and the schema gives only bare titles, so the description must compensate — and it largely does, spelling out the accepted values for 'file' and clarifying that 'content' is full YAML that replaces the file rather than a diff. Format specifics and validation expectations for the other two file types remain unstated.

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 verb and resource ('Overwrite a vault meta file') and enumerates the three valid targets (tag-dictionary | foreign-definitions | ontology-user), so an agent immediately knows the operation and scope. It stops short of naming how it relates to the many sibling writers (write_vault, patch_vault), which keeps it just below top marks.

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?

For ontology-user the guidance is explicit and mandatory: read first with read_meta, append the entry, then write the full content here. However, no guidance at all is given for the other two valid file values (tag-dictionary, foreign-definitions), and there is no statement of when to prefer this over patch_vault or write_vault, so the coverage is partial.

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