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

With destructiveHint=true and readOnlyHint=false declared, the description adds materially: nothing is persisted until the person confirms, unless assistants are permitted to make changes without asking, in which case it is saved immediately and the result says so. That two-phase, conditional-write behavior is not derivable from the annotations. It does not address reversibility or any permission model beyond the auto-apply exception.

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?

Purpose and the person's-own-words constraint are front-loaded, followed by the confirmation semantics; every clause carries information. The sentence is long and stacks multiple parentheticals, which slightly hurts scanability, but there is no filler.

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 single-parameter mutation with no output schema, the description covers the essentials: what is proposed, who confirms, and when the change actually lands (including the auto-save branch). It does not describe what a rejected or pending proposal looks like, but the 'result says so' note partially covers the return behavior.

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 100%, so baseline is 3, but the description adds genuine meaning: the statement must be in the person's own words and represents what is true about them, illustrated with two contrasting example statements. This clarifies the expected phrasing and correction-vs-addition intent beyond the schema's 'What is true about the person, in plain words.'

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 plus resource: propose a correction to something arkerah holds about the person, or add something new, in their own words. Concrete examples ('I speak Dutch fluently', 'I am junior, not senior') make the scope unambiguous, and the 'propose' framing separates it from read-oriented siblings like what_you_know_about_me.

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?

Clearly conveys the context of use: it is for changing or adding facts about the person, in their own words, and spells out the confirmation-then-save flow including the auto-apply exception. It does not explicitly name an alternative tool (e.g., reading facts via what_you_know_about_me) or state when to avoid calling it, so it stops short of full when-not guidance.

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