Create service directory

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

Goes far beyond the annotations: it discloses required scopes (files:manage on a FULL-access key, vm:files:write for the hosted connector), security refusals (execution-equivalent targets refused to every key with filesExecEquivalentScopeMissing), availability gates (agent_update_required, node_update_required, feature_disabled), and error codes (202, 409, 423). Few definitions this thoroughly expose failure modes and prerequisites.

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 core action and mode are front-loaded, and the dense remainder is operational detail rather than filler. It is a long wall of prose in a single block, which would benefit from structuring, but nearly every clause carries actionable 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?

With no output schema, the description still explains the return shape (final answer, or an operationId after waitSeconds) and the various failure responses. Combined with 80% parameter coverage and full annotation coverage, an agent has enough to invoke and interpret it correctly.

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 80%, and the description compensates for the gap by defining the undocumented 'parents' boolean ('creates missing parents and answers an existing directory as it is') and the waitSeconds polling semantics. It also implicitly explains confirmSystemPath via the 409 filesSystemPathConfirmRequired outcome.

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 specific verb+resource (create a directory) and immediately qualifies it with the mode and ownership semantics (0755, owner inherited from parent unless root). This distinguishes it cleanly from sibling file tools like write_service_file, move_service_file, and delete_service_files.

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?

Explicitly routes the agent: a slow guest's 202 is polled internally, and after waitSeconds the operationId should be continued via get_service_file_operation with the explicit warning 'never repeat the call'. It stops short of framing the tool-selection decision (when to create a directory versus other file operations), but operational usage is well covered.

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