curation_submit

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

The description goes well beyond the annotations by explaining append-only recording, atomic validation, review lookup order, backup behavior, post-recording _tags.xml reflection, and failure semantics. It also warns that an open MS-DIAL project can overwrite changes and tells the caller to relay tags_xml.note to the user. This is fully consistent with destructiveHint=true and readOnlyHint=false.

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 front-loaded with the core action and every section appears to earn its place. It is dense and long, but that length is largely justified by the tool's complexity; minor improvements in formatting could make it easier to scan.

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?

Given five parameters, 0% schema descriptions, no output schema, and a destructive mutation, the description is complete: it covers input forms, validation, review lookup, persistence, tags_xml output fields, and the MS-DIAL overwrite caveat. An agent has enough information to call it correctly and warn the user appropriately.

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 carry the burden, and it does: it defines the flags structure, allowed flag values, candidate fields, source values ('user' vs 'llm'), and the roles of review_id, file_path, and submission_text. It adds substantial meaning well beyond the bare schema.

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 that this tool records curation flags in an append-only manner, including the two submission modes (pasted text vs. direct flags). The purpose is highly specific, though it does not explicitly distinguish itself from sibling curation tools such as curation_flags or curation_suggest.

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 strong usage context: pass the pasted 'CURATION_SUBMIT' text directly, use review_id and flags for direct submission, and use separate flag schemas for candidate assignment. It also explicitly says not to call without user consent and explains atomic error behavior, but it does not name alternative tools or explain when to prefer them.

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