rhino_schedule_by_material

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

Annotations declare readOnlyHint=true, so the tool is known to be non-destructive. The description adds valuable behavioral context: how the default material is handled in Standalone mode and how Bridge mode resolves effective materials via Rhino's render content lookup. This goes beyond the annotation without contradicting it.

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 with the core action. The mode-specific details are relevant and add precision without unnecessary verbosity. Every sentence contributes meaningful information.

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 an output schema and a read-only annotation, so return format and safety are likely covered elsewhere. However, the 'fields' parameter is a significant gap: without understanding its purpose or accepted values, an agent may not invoke the tool correctly for a desired aggregation. The description covers the material grouping concept but not the full input contract.

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 description does not explain the 'fields' parameter, which is undocumented in the schema and has no default. While doc_id is partially described in the schema, the main semantic question of what fields should contain or how they affect aggregation is left entirely to the agent. Schema description coverage is low, so the description needed to compensate but did not.

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 clearly states the tool aggregates objects grouped by material name, with a specific verb and resource. It does not explicitly contrast with closely related siblings like rhino_schedule_by_layer or rhino_schedule_by_user_text, but the material grouping is clear enough to differentiate by intent.

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 implies the primary use case: aggregate objects by material. It provides mode-specific behavior (Standalone vs Bridge), but does not explicitly say when to choose this tool over schedule_by_layer or schedule_by_user_text, nor does it describe exclusions or prerequisites.

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