get_grab_operation

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

Annotations already signal mutation and destructive potential, and the description adds meaningful state behavior: 'Applied/rejected/superseded changes leave the pending set.' This goes beyond the structured hints by describing side effects on the pending set and reinforcing that the tool can update/mark, not just read. It does not fully spell out destructive consequences, but it exceeds the baseline.

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?

The description is compact and front-loaded: it quickly enumerates the tool's modes in one sentence and then adds state semantics in a second. No filler or redundant restatement of the tool name is present. The sentence is a bit dense because it packs three modes, but every clause adds needed distinction.

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 multi-mode tool with three optional parameters and no output schema, the description conveys the key invocation branches and observable state effects. Combined with the schema, an agent can understand read/update/list/batch usage. The lack of any statement about return shape or result format is the most noticeable gap, but not enough to make the description inadequate overall.

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 property descriptions cover 100% of the three parameters, so the baseline is a 3 per the rubric. The description's terms 'durable', 'legacy', and 'unified batch' align conceptually with operation_id, mark, and batch, but they do not add meaningful new semantic detail beyond what the schema already provides.

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 distinct verb+resource pairs: 'read or update one durable grab change', 'list legacy reorder operations', and 'request the unified style+reorder batch'. This clearly distinguishes the tool from related siblings like get_grab_layers and get_grabbed_elements by adding scope terms like durable, legacy, and unified batch.

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 description explains what the tool can do but does not give guidance on when to choose this tool over alternatives, nor does it provide exclusions. Phrases like 'legacy reorder operations' hint at a usage context, and schema constraints mention combinability, but the description itself leaves when-to-use versus siblings implicit rather than explicit.

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