Set a single property on a shape—like fill, stroke, font size, bold, or color—to modify its appearance.
Set a single property on a shape (e.g. fill, stroke, font_size, bold, color).
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | ||
| value | Yes | ||
| shape_id | Yes |
Changes observed during successful MCP inspections.
v0.3.1Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about error behavior for unsupported keys, whether value types are validated, whether the change is undoable, or whether it applies immediately. For a mutation tool with zero annotation coverage this is a substantial gap.
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?
One sentence, front-loaded with the verb and resource, with examples packed parenthetically. Nothing is wasted and nothing needs reordering.
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?
Three required parameters, no annotations, no output schema, and a polymorphic value field — this tool needs more than a single line. Missing are the accepted key vocabulary beyond five examples, the expected value type per key, failure behavior, and whether the call is transactional or undoable.
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 0% and the description compensates only partially: it exemplifies valid `key` values, but `shape_id` is unexplained and `value` is an untyped free-form field whose required type per key (string vs number vs boolean vs color object) is never clarified. That typing question is exactly what determines a correct call.
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 (set) and resource (a single property on a shape) and enumerates example keys (fill, stroke, font_size, bold, color), which makes the operation concrete. It does not distinguish itself from overlapping siblings like document.set_text or document.set_rotation, leaving the agent to infer whether text styling belongs here or there.
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?
The example keys imply what the tool is for, but there is no explicit guidance on when to prefer this over document.set_text or document.set_slide_background, nor on any preconditions (e.g. shape must exist, key must be supported). Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.