goodnotes_copy_text_object

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

Annotations already declare destructiveHint=false and openWorldHint=true, and the description meaningfully adds to that: it discloses a post-copy verification step (editable text, formatting, kind, appearance after reload) and confirms the source is preserved. Remaining gaps are failure behavior (what happens if verification fails), permission requirements, and whether retries or operationId replay are supported.

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 dense sentences, front-loaded with the action and scope, followed by the verification/post-condition guarantee. Nothing is redundant or padded.

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 complex mutation tool with a nested-object schema, zero parameter documentation, no output schema, and openWorldHint, the description is too thin – it omits how to identify the source object, coordinate semantics for placement, idempotency via operationId, and what a failed verification means. The verification guarantee is valuable but does not compensate for the undocumented 8-parameter surface.

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?

With 8 parameters, 7 required, a nested target object, and 0% schema description coverage, the description carries the full burden and delivers almost nothing: it never explains sourceUrl, the target object's matchId/scanId/objectId/query selectors, destinationPath, destinationPage, the x/y coordinate ranges, or operationId idempotency. Only the notion of expected text verification is faintly implied by "Verifies editable text".

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 specific verb and resource ("Copy one verified native text box or sticky") and names the destination ("another document/page"), which separates it from siblings like copy_image_object, copy_page, or copy_native_selection. It doesn't explicitly reference those alternatives, but the object-type restriction is clear enough to disambiguate.

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?

Usage is implied rather than stated: the tool is for single-object copies of already-verified native text/sticky objects, and "leaves source intact" implicitly contrasts with a move. There is no explicit when-not guidance, no mention of prerequisites (e.g., that the target object must be located/verified first), and no pointer to goodnotes_move_native_object or goodnotes_verify_copied_object.

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