max_api

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

With no annotations, the description carries the full burden and does unusually well: it discloses the KNOWN BLIND SPOT (only class-declared members; universal node properties absent even from getPropNames), which is exactly the kind of behavior an agent would otherwise get wrong. It does not explicitly state that the call is side-effect-free or describe output shape/pagination, which is why it stops short of a 5.

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?

Well front-loaded: purpose first, then the blind-spot warning, then args. The anecdote about six wrong assumptions in this session is motivating but slightly verbose and consumes lines that could have carried output-shape detail, so it's efficient but not maximally tight.

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 2-parameter read/reflection tool with no output schema and no annotations, the description covers what is returned (declared member names, filtered by pattern), the critical failure mode, and where to go instead. Nothing an agent needs to invoke this correctly is missing.

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%, so the Args block is doing real work: `class_name` is given concrete examples ('Box', 'Editable_Poly', 'VRayLight') and `pattern` is defined as a MAXScript wildcard with default '*' plus a narrowing example ('*segs') and the output-length implication. It stops at 4 because it leaves open edge cases such as invalid class names or case sensitivity, which it flags as a hazard elsewhere but doesn't resolve here.

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?

Opens with a specific verb and resource ('List the members a class DECLARES'), with 'DECLARES' capitalized to signal the scope boundary. It explicitly separates itself from max_check (for node-level universal properties) and max_api_search (which won't find the abstract node class), so an agent can route between siblings without opening 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?

Gives a clear directive ('Reflect instead of guessing') plus a concrete when-not: for `name`, `pos`, `wirecolor`, `isHidden`, `isFrozen`, `parent`, `material`, use max_check instead. It also names max_api_search as a non-viable alternative for those cases. This is explicit when/when-not/alternatives guidance.

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