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

'Sends nothing' rules out outbound messaging and is consistent with openWorldHint=false, while the content rule ('never invent prices, offers or promises') and the needs_a_person escalation path add real policy context beyond the annotations. It does not spell out that knowledge_mode=replace overwrites existing sections, which is the main behavioral detail left to the schema and the destructiveHint.

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?

Roughly 60 words with no filler sentences, and the write-scope rule ('send only the parts to change') is placed near the front. The permissions sentence is dense and needs a second read, but every clause carries a distinct constraint.

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 7-parameter nested mutation tool with an output schema and full schema coverage, the description covers the risky parts: partial updates, the content-invention prohibition, and the agent-must-not-enable boundary. A note that replace mode can wipe existing knowledge sections would make it fully complete.

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% and every nested object carries a description, so the baseline is 3. The description contributes partial-update semantics and reinforces the one-way constraints on answers/approve_first, but those values are already visible in the schema, and goal/tone/safety params get no extra meaning.

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 states the tool writes what Postkey AI 'knows and how it answers', which maps to the knowledge/tone/goal/safety settings, and its write framing implicitly separates it from the read-only postkey_get_ai_replies sibling. The phrasing is indirect ('Saves what...') rather than a crisp verb+resource, so an agent gets the gist but has to translate a bit.

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?

Strong actionable guidance: 'Send only the parts to change' establishes partial-update use, and the sentence about switching answers off versus needing the person's own tap for switching on or approve_first=false defines an explicit case the agent must not do itself. No sibling alternative is named, which is the only gap.

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