Read a MAtricks object

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

With no annotations, the description carries the burden and does so credibly: it declares the operation is read-only, sends no command, defines the {from, to} distribution format, and explains that null means None. It also discloses that non-default settings are listed. Missing only auth/permission or scope caveats, which are minor for a read.

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 read-only qualifier and resource are front-loaded in the first two words, and the dense field list earns its space by telling the agent exactly what comes back. It is lengthy but not padded; a slightly lighter field enumeration would read more cleanly.

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?

No output schema or annotations exist, so the description must convey return shape, which it largely does by enumerating fields, defining the distribution format, and specifying null semantics. A read-only single-param tool is well covered, though permission prerequisites are unstated.

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 coverage is 100% and the single required parameter is already documented as 'MAtricks pool number'. The description's 'MAtricks <n>' restates this without adding format, range, or default detail, so it earns the baseline 3 with no extra value.

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 precise verb ('Read') and resource ('MAtricks object'), then enumerates the exact settings returned (wings, blocks, groups, width, shift, shuffle, fade/delay, phase, speed distributions). An agent can distinguish this inspection tool from gma3_configure_matricks and the command-sending siblings without opening the schema.

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 'Read-only' and 'Sends no command' framing implies this is for inspection rather than mutation, which is useful context. However, it never names the write alternative (gma3_configure_matricks) or says when to prefer this over gma3_get_object/gma3_dump; usage is left to inference.

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