r7_slide_object

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

With no annotations, the description carries the full behavioral burden. It does add real value by claiming existing media/relationships are "never damaged" and that geometry, fill, border, text and font are applied in one call. But it omits that 'remove' is a permanent destructive action, whether edits are in-place versus copied, and what the call returns (the schema references ids "reported by r7_slide_read", implying output exists but that is never stated).

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 sentences, front-loaded with the core verb+resource and object types, then behavior, then the replaceImage special case. The parenthetical shape list is verbose but informative. No filler sentences.

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 51-parameter tool with 94% schema coverage and no output schema, the description supplies the essential framing: what can be created/removed, the single-call composition model, and the swap-picture mode. Since the schema covers parameters and no output schema must be explained, the remaining gap (the five action modes are only partially elaborated) is minor.

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 description coverage is 94%, so the schema already documents nearly every parameter, including units, enums and defaults. The description mostly restates schema content (the shape preset list is duplicated) and adds only the replaceImage/geometry-preservation nuance. Baseline 3 is appropriate when the schema does the heavy lifting.

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 uses a specific verb+resource ("Add or remove objects on a PPTX slide") and enumerates the object kinds (shapes, text boxes, images) plus the special replaceImage mode. It is clearly distinguishable from sibling r7_slide_read, though it does not explicitly contrast with r7_slide_edit or r7_slide_format, which could also parse as object-mutating.

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?

It gives one concrete usage hint ("Set action \"replaceImage\" with an existing image object's id to swap its picture"), which points the agent at the right action. However, there is no guidance on when to use this tool versus r7_slide_edit, when to prefer addShape over addTextBox, or any exclusion criteria. Usage is implied rather than stated.

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