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

The description adds a key behavioral trait beyond annotations: 'Changes nothing until decided,' clarifying that the tool is non-mutating pending approval. This is important context even though annotations already indicate destructiveHint=false. It also imposes a workflow requirement to attach evidence and confidence, but does not cover permissions, rate limits, or what happens on approval.

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 a single tight paragraph front-loaded with purpose and behavior. Every sentence contributes: purpose, non-mutation guarantee, evidence/confidence instructions, and the 'start here' directive. No wasted words.

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 the complex nested proposal object and 0% schema description coverage, the description provides adequate high-level context but is incomplete for an agent to construct a correct proposal without inspecting the schema. The output schema exists, so return values are covered, but the input structure remains underexplained.

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 compensate. It explains the change kind implicitly by listing possible actions, and it highlights evidence, confidence, and ambiguity_note. However, it does not explain the structure of core fields like proposed, prior, or how to populate most of the nested proposal object, leaving significant gaps.

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 ('Proposes') and explains that the tool creates a change for member approval, listing concrete actions (create/edit relationship, move stage, record touch, update raise plan, hand commitment to cap table). This distinguishes it from direct-write siblings by making clear it is a proposal step, not the write itself.

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 explicitly says 'This is how every agent write should start,' giving a clear default context for use. It also provides guidance on setting confidence and using ambiguity_note when evidence is ambiguous, though it does not name specific sibling tools to avoid or state exclusions.

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