get_grabbed_elements

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

The description characterizes the tool as a safe read operation ('Read ... without deleting their durable change records'), while annotations mark it as destructiveHint=true and readOnlyHint=false. This is a direct behavioral contradiction: either the description understates destructive side effects or the annotation mislabels the tool. The agent cannot rely on either signal.

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 tool is concise and front-loads the core action in the first sentence, but the second sentence ('A batchCommit marker is the signal... to implement the unified pending batch') introduces opaque, implementation-heavy language that is not actionable for an agent. It is not fatally verbose, but it does not earn its place.

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?

The tool has no output schema and no description of what is actually returned after reading the grab selections, and the behavior is made less safe by the annotation contradiction. The cryptic batchCommit sentence hints at a workflow contract but does not explain how the agent should recognize or respond to that condition, leaving the description insufficient for correct invocation.

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?

There is only one optional parameter, and the schema description already covers its meaning: 'Optional wait timeout in milliseconds'. The description merely restates 'optionally waiting up to timeout_ms', adding no new semantic detail beyond the schema, so the high-coverage baseline of 3 applies.

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 opens with a clear verb and resource: 'Read newly sent grab selections' and adds a meaningful qualifier ('without deleting their durable change records'), which helps distinguish a reading tool from a purging one. It could be strengthened by explicitly naming how it differs from sibling tools like get_grab_layers or get_grab_operation, and the second sentence's batchCommit jargon muddies the purpose.

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 phrase 'newly sent grab selections' and 'batchCommit marker' give implied context for when this should be used, but no explicit alternatives or exclusions are provided. An agent would still need to infer the tool's role among 100+ siblings, and there is no guidance about what to use if destructive behavior is desired.

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