ap_get_main_object

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

With no annotations, the description carries the behavioral disclosure burden. 'Describe' communicates a non-mutating read operation and lists the returned data (name, visibility, transform). It does not state output format or possible absence of a main object, but for a no-argument getter the key side-effect-free behavior is clear.

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?

A single sentence front-loads the action and resource, then lists the relevant details in a compact parenthetical. Every word earns its place; there is no repetition of the tool name or filler.

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 simple no-argument, read-only getter, the description is nearly complete: it names the target and the contents of the description. It does not explicitly say that the result is returned vs written to console, but 'Describe' plus the get_* naming makes this reasonably clear even without an output schema.

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?

The tool has zero parameters and schema coverage is trivially 100%, so the description need not explain parameters. The baseline for zero-parameter tools is 4, and the description correctly focuses on what the tool returns rather than arguments it does not take.

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 states a specific action ('Describe') and resource ('main paint object'), and enumerates the exact attributes covered: name, visibility, and transform with location, rotation quaternion, and scale. The qualifier 'main' clearly differentiates this from sibling ap_get_object and the setter tools, so an agent can distinguish it without looking at schemas.

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 establishes a clear use: retrieve information about the main paint object. It does not explicitly mention alternatives or exclusions, but naming 'main paint object' rather than generic 'object' gives enough context to avoid confusion with ap_get_object or transform/visibility setters.

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