session.capabilities

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

Annotations already include readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds a bit of context with 'Requirements: Per-request argument checks and session policy still apply' which suggests the call may be subject to validation, but it does not describe what the tool does or returns. 'Risk: read' is redundant with the annotations. There is no scoping or side-effect disclosure beyond what structured data provides.

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?

While short and not bloated, the description wastes characters by restating the title ('PartMe Blender Harness command session.capabilities') and repeating the read-only risk already in annotations. The maturity L3 note is new but unexplained. Not every sentence contributes to the agent's ability to invoke the tool correctly.

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 surrounding context includes many session and capability-related siblings (e.g., blender_capability_list, blender_session_status), but the description is too thin to let an agent understand what this tool uniquely provides. The output schema may define the return structure, but the purpose is still unclear, so the description is incomplete for a tool with zero required parameters and mostly metadata inputs.

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 how the parameters (e.g., _expectedSceneRevision) affect the command, and it does not compensate for the ~25% of parameters lacking a schema description. The statement about 'per-request argument checks' implies parameters matter little but offers no semantic mapping. With a schema covering most but not all, the description adds no parameter 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?

The description restates the command name `session.capabilities` and adds metadata (Risk: read, maturity: L3) but never states what the tool actually does, such as returning a list of capabilities for the current session. It does not distinguish it from sibling tools like blender_capability_list or blender_capability_describe, so the agent cannot infer the tool's function.

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?

No when-to-use or when-not-to-use guidance is provided. The description does not mention any conditions, prerequisites, or alternatives. The 'Requirements' note is about the execution environment, not about selecting this tool over others. With a sibling group of ~? Capability tools, this is a significant gap.

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