dsh_attach_session

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

Annotations are all false, giving little guidance beyond the lowest-level safety flags. The description compensates well by stating that it creates/reuses bridge-local state, starts reconciliation, and will not perform a list of DSH-related mutations or data transformations. It does not cover failure modes, error returns, or potential side effects on the bridge beyond what is described, but the core behavior is laid out clearly.

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 three front-loaded sentences: the action, the effects/exclusions, and the follow-up instruction. It is effective and relevant. It is slightly dense with multiple compound clauses, but every phrase adds behavioral or routing value, so it is not wasted text.

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?

There is no output schema, so the description carries the burden of saying what happens on success: creating/reusing mapping/claim state and starting supervision, with a defined next step. It nicely scopes out many side effects (does not prompt, create, rename, persist, or route). What is missing is any guidance on failure cases, e.g., what happens if the discovery preconditions don't match, or whether the tool can outright fail. That keeps it from a 5.

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 descriptions cover 50% (expectedCwd, expectedTitle, workspaceMode). The description adds a small amount of contextual glue by calling the expected fields 'fresh discovery preconditions' and emphasizing 'exact', which clarifies expectedUpdatedAt and expectedTitle. But it does not explain allowBlank at all, and the role of expectedUpdatedAt is only inferable as a precondition after attaching session's stale or not. This is better than empty, but does not fully close the schema's coverage gap.

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 opens with a specific verb-resource pair: 'Attach one idle existing root DSH session to the bridge using its exact sessionId and fresh discovery preconditions.' It also enumerates what the tool does not do (prompt DSH, create or rename sessions, return/persist conversations, change routing), which effectively distinguishes it from sibling tools such as dsh_followup and dsh_delegate.

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?

It gives clear triggers: attach when there is an idle existing root DSH session and you have exact sessionId plus fresh discovery preconditions. It also states the follow-up path ('After success, use dsh_followup with a compact handoff when work should continue'), which is useful routing guidance. It stops short of explicitly listing alternatives to not use under certain circumstances, and could have said 'do not use if the session is not idle'.

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