goodnotes_write_text

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

Annotations already declare a destructive, non-read-only, open-world write, and the description goes well beyond them: it specifies that an empty string only clears a read native shape label while preserving the shape, that results are verified by reloading and checking exact text and native kind, and that retries must reuse the operationId. That is exactly the idempotency and side-effect detail an agent needs before a destructive write.

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?

Three tight sentences with the destructive-scope constraint front-loaded before the edge-case rules and the retry warning. Dense but no sentence is filler; the empty-string rule could arguably be split for readability but the ordering is sensible.

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 destructive three-parameter write with no output schema and zero schema-level descriptions, the definition covers preconditions, the special empty-string case, post-write verification, and idempotency. What remains thin is the relationship to sibling text tools and the size limit on text.

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 0%, so the description carries the burden. It adds real meaning for operationId (uniqueness and no fresh IDs on retry) and for text (empty-string clearing behavior), but says nothing about the 8000-character limit or the UUID target format, leaving part of the parameter surface undocumented.

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 names a specific verb and resource ('Replace the text of a previously read target') and constrains the scope to a locally allowed document, which separates it from creation tools like goodnotes_create_text. It does not explicitly contrast with the closely named goodnotes_edit_text sibling, leaving the agent to infer the split.

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?

Preconditions are stated clearly: the target must have been read previously and the document must be locally allowed. Operational guidance about using a unique operationId and never retrying an uncertain write with a new ID is concrete and actionable. It stops short of naming an alternative tool when the preconditions fail.

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