Set Native Mindmap Lock

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

Annotations only state readOnly=false and destructive=false; the description goes well beyond with inheritance semantics ('nodes inherit the lock'), partial-unlock behavior (ancestor-group and independently locked flags persist), side-effect scoping ('does not change layout or styles'), and a security caveat. For a mutation tool this is unusually complete behavioral disclosure.

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 short sentences, each carrying distinct information: the action, the inheritance rule, the unlock caveat, and the scope boundary. Nothing is repeated and the core action is front-loaded.

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 needn't be explained, and annotations cover safety. What remains thin is the optional workspaceId parameter and any permission requirement for locking a shared mindmap; otherwise the definition is sufficient to invoke the tool 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 coverage is only 20% — only expectedRevision is documented in the schema. The description clarifies what the `locked` boolean actually means (native lockedBySelf flag, inherited by nodes) but says nothing about workspaceId's optional role or the docId/mindmapId relationship. Partial compensation, consistent with a 3 when coverage is low.

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?

States a precise verb and resource ('Set the mindmap's native lockedBySelf flag') and names the exact flag being mutated, which no sibling tool touches. It explicitly excludes set_mindmap_layout and set_mindmap_style, so an agent can route correctly among the mindmap siblings without opening schemas.

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 gives clear context for the operation ('editor lock, not an access-control boundary') and tells the caller to read the returned effective locked state after unlocking, which is a concrete follow-up instruction. It does not explicitly say when to use this versus an access-control mechanism (e.g. publish/revoke), leaving that to inference.

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