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

Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the safety profile is supplied. The description earns credit by adding genuinely new behavioral detail beyond them: partial-update semantics ("Only the fields you pass change") and loss of prior text ("the old text is overwritten"). It still does not say whether overwrites are reversible or what the response contains.

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?

Two short sentences with the mutation scope and the partial-update rule front-loaded; every clause carries information an agent needs. No filler or restatement of the title.

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?

For a 4-parameter destructive mutation with no output schema, the description covers the edit semantics but omits what the call returns and any constraint on the required id beyond the schema's one-line note. Annotations cover the safety profile, so the remaining gap is modest but real.

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 25% (only id is documented), so the description must carry the rest, and it does name all three optional fields, clarifying that "text" maps to the body parameter and that pinned is a boolean toggle. It adds little meaning beyond the parameter names themselves, which are largely self-evident, so it is adequate but not compensating fully for the low coverage.

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?

"Changes a note in the couple's ideas" gives a specific verb and resource, and the field list (title, text, pinned) pins down what is editable. It reads clearly as the mutation counterpart to add-idea/delete-idea, though it never names those siblings explicitly.

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?

There is no explicit when-to-use guidance, no prerequisites, and no comparison to add-idea or delete-idea. The agent can infer that this is the modify path for an existing note, but nothing states when to prefer this over deleting and re-adding, or what happens on an unknown id.

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