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

Goes well beyond the annotations by declaring the required permission (executor.run), that a generated key pair is shown only once, exactly what is returned (host, port, host key, expiry), the vault interpolation and masking behavior with its own permission requirement (secrets.use), and the no-port-forwarding limitation. This is materially useful context an agent cannot get from readOnlyHint/destructiveHint alone.

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?

Front-loads the action and prerequisite, then layers in return values and vault semantics in compact clauses. Dense but nearly every clause carries distinct information; only the vault-agent clause feels slightly tangential to the core action.

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 credential-issuing tool with no output schema, it covers return values, permission prerequisites, key lifecycle, and client compatibility. The one gap is the unexplained result_offset parameter and no note on how many results or whether repeated calls create multiple credentials.

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?

With 0% schema description coverage the description must carry the load: it explains public_key well (bring your own ed25519 key or omit it) and implies project_id via 'THIS project's sandbox'. However, result_offset is never mentioned, so one of three parameters remains undefined in both schema and description.

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 and resource — open a direct SSH channel into THIS project's sandbox on the executor — and scopes it to the current project. It is readily distinguishable from siblings such as executor_ssh_run or executor_run because it describes obtaining credentials/connection details rather than running commands.

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 concrete operating conditions: needs executor.run, supply your own public_key or omit it to have a pair generated, and the resulting host/port work with scp, sftp and rsync while port forwarding is unsupported. It does not explicitly say when to prefer executor_ssh_run or executor_sandbox instead, so the alternative routing is only implied.

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