cad_document

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description does not contradict them. The description adds that paths must be absolute local paths and that save/saveAs/overwrite semantics exist via parameters, but it does not disclose which actions are destructive (e.g., overwrite behavior, close discarding changes), the risk of saving over files, or authentication/permission needs. Given the destructive hint is already present, the gap is moderate rather than severe, so 3 is appropriate.

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 one concise sentence that front-loads the action list and then the critical path constraint. Every word earns its place and there is no filler. It loses one point only because it is so terse that it omits important usage context that would fit naturally in another sentence.

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 9 parameters, a large sibling set, no output schema, and only minimal annotations, the description is under-specified. It does not explain which parameters apply to which actions, the meaning of documentId vs path, the dependencies between action and other parameters, or the safety implications of destructive flags like overwrite and discardChanges. An agent would need to probe the tool or make risky assumptions to call it correctly.

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 very low (11%) and there are 9 parameters, mostly undocumented. The description adds almost no parameter-level meaning: it implies path is the document path and action is one of the verbs, but it does not explain documentId, template, overwrite, readOnly, discardChanges, password, or version. The enum on action is self-descriptive, but the other seven parameters require inference, so the description fails to compensate for the schema gap.

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 names a specific verb list and resource ('Create, open, save, save-as, close, activate, or list AutoCAD drawings') and states a key constraint (absolute local paths). It identifies the tool as the document lifecycle manager within a large sibling group (cad_document vs cad_draw/cad_edit/cad_view etc.), so an agent can reasonably distinguish it without opening the schema. However, it doesn't name any sibling explicitly, and the verb list bundles many actions into one description rather than isolating the one the tool is for.

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 the tool is for file-level document operations versus drawing, editing, or inspecting (implied by the verb list), but it gives no explicit when-to-use versus alternatives or exclusions. The path constraint is stated, which is useful operational guidance. Siblings like cad_draw, cad_edit, cad_view, and cad_workflow are not mentioned, so an agent must infer routing from the action verb list.

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