Server Quality Checklist

Tool Scores

• dsh_observeB
  3.2/5.0
  Behavior4/5

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

  The annotations already communicate read-only, idempotent, and non-destructive behavior, so the description's burden is lower. The description adds deprecation/compatibility context and indicates that the intended operation is covered by dsh_wait plus dsh_tail, which is behavior that annotations cannot express.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Both sentences are short and front-loaded, and there is no wasted wording. It loses a point because the description is under-specified rather than merely concise, especially around what the compatibility alias does and how its parameters behave.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a compatibility-only alias, the description provides adequate routing and safety context. However, because there is no output schema and the description never states what the call returns or how cursor/wait semantics behave, the overall picture is incomplete for an agent that actually needs to invoke this tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters1/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0%, and the description does not compensate at all, saying nothing about taskId, afterCursor, or waitSeconds. An agent must infer the meaning of all three parameters from bare names, patterns, defaults, and constraints, which is insufficient for correct invocation.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose3/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description identifies dsh_observe as a 'compatibility observation alias' and points to dsh_wait/dsh_tail, so an agent knows roughly where it belongs. However, it never states what the observation actually does, what resource it targets, or what kind of result the agent should expect, leaving the purpose somewhat vague.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  "Prefer dsh_wait plus dsh_tail task cursors" is an explicit routing instruction with named alternatives, which is genuinely useful. What is missing is the corresponding 'when not to use' and 'when it is acceptable to use this compatibility alias' guidance, though 'compatibility' provides part of that context.

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

• dsh_tailB
  3.2/5.0
  Behavior4/5

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

  Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful beyond-annotation context: content is fetched from DSH history when reachable and is never copied into bridge persistence. This helps the agent understand external reachability and data-hygiene semantics, though failure behavior when history is unreachable is not disclosed.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences from the core behavior without fluff. The action, the resource, the mechanism, and the key data-handling constraint are all stated efficiently and front-loaded into the first sentence.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  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 is responsible for shaping an adequate mental model. It does not explain the meaning of the four parameters, how a cursor should be obtained or advanced, or what a digest structurally contains. The description is useful but not complete enough for a correct invocation beyond trial and error.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema description coverage is 0%, so the description must compensate for the undocumented parameters. It hints at the 'bounded' nature of maxBytes/maxEvents and at 'cursors' for sinceCursor, but it never maps these concepts to any named parameter or explains their roles. taskId remains completely unaddressed.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a clear verb ('Read') and resource ('bounded event digests'), so an agent knows what the tool does. It also adds the mechanism ('bridge coordination cursors'), though it does not explicitly differentiate it from sibling tools like dsh_observe or dsh_list.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  There is no explicit guidance on when to use this tool versus alternatives. The phrase 'bounded event digests' implies a history/tail-style use case, but the description never states conditions, exclusions, or which sibling tool might be more appropriate. This is essentially absent guidance.

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

• dsh_statusB
  3.4/5.0
  Behavior4/5

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

  The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by revealing the shape of the returned state: separate availability/execution state, root versus descendant sessions, queue depths, pending interactions, and bridge-local workspace semantics. This clarifies what the status contains beyond what the generic read-only annotation implies.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Everything is packed into one dense, roughly 30-word sentence with no filler or repeated structured data. It is front-loaded with the action 'Return' and then lists distinct pieces of state. The slash-separated enumeration is compact, though slightly harder to parse than a structured list would be.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a read-only one-parameter tool, the description gives a good sense of what the output will cover and the input schema covers the expected ID format. However, the terms 'bridge cursor/watermarks' and 'bridge-local workspace claim semantics' are not explained, and there is no output schema to clarify the exact return representation. This leaves interpretation gaps for an agent despite the invocation being straightforward.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema has one required parameter, taskId, with a pattern but no written semantics, and the description does not explicitly explain what taskId refers to. However, the tool name and the status content strongly imply taskId is the dsh task being inspected. The parameter is self-evident enough to be callable, but the description does not compensate for the missing parameter documentation in a meaningful way.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description starts with a clear verb 'Return' and names a specific resource: the status object containing availability/execution state, sessions, queue depths, pending interactions, final answer, and bridge-related cursors/watermarks. It distinguishes itself from siblings like dsh_host_status and dsh_find_sessions by listing compound status content, but it does not explicitly state that the tool returns this for the given taskId.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  There is no guidance about when to use dsh_status versus dsh_wait, dsh_tail, dsh_observe, or dsh_continue. The description implies this is a read-only snapshot, but it never states that it is non-blocking, that it should be used for a point-in-time check, or that other tools cover waiting/tailing/observing behavior.

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

• dsh_host_statusA
  3.5/5.0
  Behavior3/5

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

  Annotations already disclose that this is read-only and idempotent, and the description reinforces that by saying 'report.' It adds some context about what is reported but does not disclose return format or potential operational behavior such as network dependency or staleness. No contradiction exists.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, information-dense sentence with no filler. Every phrase contributes meaning, and the main subject is front-loaded.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a zero-parameter, read-only status tool with strong annotations, this description is adequate. It could be slightly more complete by saying what shape the report takes or what counts as a 'capability,' but the operational risk and ambiguity are low.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The tool takes zero parameters, so there is no parameter semantic burden on the description. The schema is empty and correctly set to disallow additional properties.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a clear verb ('Report') and names the two things being reported: the connect-only bridge state and DSH Web Host capabilities. It is reasonably specific, though it does not explicitly differentiate itself from the sibling dsh_status tool.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives no guidance on when to use this tool versus alternatives like dsh_status or dsh_observe. It implies a general status-checking use case but does not state exclusions or conditions for selecting another sibling.

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

• dsh_cancelA
  3.6/5.0
  Behavior4/5

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

  Annotations already mark the tool as destructive, and the description adds genuinely useful behavior beyond that: the turn scope explicitly preserves queued work, and queue removal is described as non-atomic and based on the latest mux queue snapshot. This is meaningful transparency about what gets destroyed.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is compact, front-loads the primary scope behavior, and either sentence earn its place. No redundant text, no restating of the tool title or generic cancellation wording.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a destructive 4-parameter tool with no output schema, the description does not explain return behavior, partial failure states, or the semantics of sinceCursor/expectedRevision. The scope behavior and non-atomic queue removal are helpful, but important invocation context is still missing.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema has 0% description coverage and the description only explains the scope enum. taskId, sinceCursor, and expectedRevision are left completely unexplained, so the agent cannot infer the meaning of important parameters like optimistic concurrency guards or cursor-based synchronization.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states concrete behavior for each scope: scope=turn cancels the active root turn and preserves queued work, while scope=queue removes queued items. It is clear about what the tool operates on, though it does not explicitly distinguish itself from sibling tools by name.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives clear context for choosing a scope, including that it not’s queued work and that queue removal is non-atomic. It does not provide when-not-to-use guidance or name alternatives like dsh_continue or dsh_release_workspace, so it stops short of very explicit routing.

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

• dsh_resolve_approvalA
  3.7/5.0
  Behavior3/5

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

  The annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds a policy-level behavioral trait: the tool does not auto-allow and must be gated by human approval. However, it does not disclose what actually changes on allow_once vs reject, such as side effects to the DSH sandbox or any return feedback.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences with no filler: the first states the core action and allowed outcomes, the second gives the critical safety guardrail. It is front-loaded and all content is relevant to safe invocation.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a 5-parameter mutation with no output schema, this description is thin. It does not explain what the optional sinceCursor and expectedRevision are for, how a pending approval is selected, or what the result of resolving one is. The safety guardrail is useful, but the rest of the invocation context is missing.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0%, so the description must compensate, but it only repeats the allow_once/reject concept from the outcome enum. It gives no semantics for taskId, requestId, sinceCursor, or expectedRevision; the agent has to rely on parameter names and schema constraints alone to understand how to identify and resolve the right pending request.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description names a specific action ('Resolve') applied to a specific resource ('one pending DSH sandbox-escalation approval') and states the two possible outcomes ('allow_once or reject'). This is precise and clearly distinguishes the tool from the listed sibling tools, none of which are described as resolving the approval workflow.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives a direct operational constraint: never auto-allow and keep the tool behind the caller's human approval prompt before using it to allow_once. This tells the agent when it is appropriate to invoke this tool. It doesn't explicitly compare against alternative tools, but no sibling appears to serve the same approval-resolving purpose.

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

• dsh_answer_questionA
  3.8/5.0
  Behavior4/5

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

  Beyond the annotations (all false), the description adds meaningful behavioral detail: validations are performed locally, the operation results in exactly 'one non-retried /api/respond write'. This discloses retry semantics and the mutation path, which is useful for an agent deciding whether to invoke or expect idempotency. It does not contradict any annotation; readOnlyHint false aligns with 'write'.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description earns its two sentences. The first sentence front-loads the core action in clear terms, and the second adds dense behavioral context without fluff or redundant repetition of the schema. Every phrase contributes to helping an agent understand the tool.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a 5-parameter write tool with no output schema, the description is largely complete: it explains the core action, known validation, and write behavior. Optional parameters like sinceCursor and expectedRevision lack any contextual hint in the description or schema property descriptions, which is the main gap preventing a perfect score.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  With schema description coverage at 0%, the description carries the naming burden. It partially succeeds by referencing 'requestId', 'task lineage', 'question ids/order', and 'selections', mapping loosely to requestId, taskId, answers[].id, and answers[].selected. However, optional parameters sinceCursor and expectedRevision are omitted, and there is no explicit mapping to the schema's custom field or the shape of the answers array.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's action ('Answer') and resource ('one currently pending typed DSH question request'), making it immediately obvious what the tool does. It lacks an explicit distinction from sibling tools like dsh_continue or dsh_followup, but the phrase 'currently pending typed DSH question request' narrows the purpose enough for an agent to separate it from general session or status tools.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The phrase 'currently pending typed DSH question request' implies when to use the tool: when there is a pending question to be answered. However, the description does not explicitly say when not to use it or which sibling alternative to prefer (e.g., dsh_continue, dsh_followup). Usage guidance is implied rather than stated, leaving some room for an agent to misroute a call.

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

• dsh_listA
  3.8/5.0
  Behavior4/5

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

  Annotations already establish readOnlyHint, idempotentHint, and destructiveHint false. The description adds meaningful behavioral context by mentioning 'current derived DSH status' and 'bridge-local workspace-local claim semantics', which are beyond what annotations reveal. It also conditionally scopes enrichment to Host reachability, although it does not specify behavior when the Host is unreachable.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is one sentence, front-loaded with the action and resource, and uses no filler. It packs the key qualifiers (status enrichment, local workspace-local semantics, Host reachability) into a compact but coherent phrase. Every element contributes meaning.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  With zero parameters and no output schema, an agent relies almost entirely on this description to understand what it will get. The description says mappings are enriched, but never describes the return shape, ordering, or what happens when Host is unreachable. It is enough for basic selection, but incomplete for confidently predicting behavior.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The tool has zero parameters, and the schema coverage is complete by that baseline. There is therefore no parameter-semantic gap for the description to fill. Per the rubric, zero-parameter tools receive a baseline score of 4.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific action and resource: 'List bridge task mappings' with enrichment. It clearly indicates this is a read-only listing of bridge task mappings, which differentiates it in topic from most siblings. However, it does not explicitly distinguish itself from dsh_find_sessions or dsh_status, so sibling differentiation is only implied.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The phrase 'when the Host is reachable' hints at an operating condition, and calling the tool after 'bridge task mappings' suggests it is for enumerating current mappings. But the description never states when the tool should be preferred over siblings or when not to use it. The usage is implied rather than explicit.

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

• dsh_waitA
  4/5.0
  Behavior4/5

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

  Annotations already indicate read-only, idempotent, and non-destructive behavior, so the description's task is lighter here. It adds useful behavior not present in the annotations: the operation is time-bounded to 30 seconds and will not keep waiting until a task completes. It also describes the event categories that trigger a return, which a caller otherwise could not infer from the schema or annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is very efficient: one sentence states the core behavior and timeframe, and the second sentence narrows expectations with an explicit negative. The wording is front-loaded so the agent sees the crucial limitations immediately. There is no filler or repetition of available structured metadata.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple, read-only, idempotent wait tool with three flat parameters and no output schema, the description covers the main gaps: bounding timeout, trigger conditions, and non-completion behavior. The only shortfall is that it does not say what the tool returns when a timeout or event occurs, but this is largely inferable from a wait tool with a cursor parameter.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0%, so the description must compensate, but it only partially does. 'At most 30 seconds' maps clearly to timeoutSec, and 'new task cursor' hints at sinceCursor, but taskId is not explicitly described and the cursor mechanics remain vague. The parameter names and schemas are fairly self-explanatory, but the description does not fully replace the missing per-parameter documentation.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the specific operation: wait at most 30 seconds for a new cursor, status/availability change, terminal state, or pending interaction. It does not just repeat the tool name and it explicitly bounds what it is not doing by saying it never waits for whole-task completion. It avoids naming a sibling tool, but the event categories are precise enough to separate it from status, tail, and observe tools.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives a clear when-to-use context: when the agent needs to wait for cursors, state changes, terminal states, or pending interactions. The phrase 'It never waits for whole-task completion' is an explicit exclusion that prevents misuse. It does not point to a specific alternative tool, but the intended use is reasonably delineated.

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

• dsh_attach_sessionA
  4.1/5.0
  Behavior4/5

  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.

  Conciseness4/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• dsh_delegateA
  4.3/5.0
  Behavior4/5

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

  It discloses several non-obvious behaviors: the call is detached by default, explicit model selection persists as the DSH default via session.selectModel, and workspaceMode is only a cooperative local claim, not a sandbox verifier. These go beyond the uninformative annotations. The description doesn't say what the call returns, but it still carries substantial transparency burden well.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is front-loaded with the main purpose and then organized around actionable instructions. It is longer than minimal but each sentence earns its place; the only slight redundancy is repeating that explicit user choices take precedence before explaining session.selectModel persistence.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  With no output schema and several complex fields, the description completes most of the Agent's decision loop: what to prepare, how to route, and why workspaceMode is not a sandbox claim. It leaves a small gap by not stating what the call returns or how to coordinate with dsh_wait, dsh_find_sessions, and dsh_attach_session, but those appear as siblings and are inferable.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 67%, and the description adds meaning beyond the schema for prompt construction, modelProfile routing and precedence, and the workspaceMode caveat. It doesn't elaborate on waitSeconds or the literal return identity, but the most decision-critical parameters are given practical semantic context.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The opening sentence clearly states the action: "Create a root session on the configured official DSH Web Host and queue the initial prompt." It identifies a specific verb and resource, and the "root session" phrasing distinguishes it from sibling attach/followup tools that work on existing sessions.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives concrete pre-call guidance: include a compact handoff with read-only evidence, identify focus paths, and tell DSH to read those first. It also explains when to choose pro versus modlens profiles and when to omit routing fields. It does not explicitly name "use dsh_attach_session instead for existing sessions," but the focus on initial root session makes the intended case clear.

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

• dsh_release_workspaceA
  4.3/5.0
  Behavior4/5

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

  Annotations already mark the operation as non-readonly and potentially destructive, but the description adds valuable behavioral context: it releases a claim while leaving the session open and not affecting other clients' editing. This goes beyond the annotations with meaningful side-effect disclosure.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two crisp sentences deliver the core action and the key negative side effect without redundant framing. Every sentence earns its place.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a one-parameter operation with this scope, the description fully covers the action, the affected resource, and the main misinterpretation risk. The absence of an output schema does not leave a serious gap because the tool's primary purpose and non-effects are clearly stated.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema only defines taskId with a pattern and provides no description. The tool description references 'this bridge task's persistent workspace claim,' which suggests taskId identifies the relevant bridge task, but it does not explicitly explain the parameter semantics or where the value comes from in the schema. With schema coverage at 0%, the description could compensate more.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb ('release') with a specific resource ('persistent workspace claim') and immediately clarifies the boundary ('does not close the DSH session...'). This clearly identifies what the tool does and distinguishes it from session-level or editing commands.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The phrase 'explicitly release this bridge task's persistent workspace claim' makes the intended situation clear, and the statement about not closing the session or blocking other clients provides a useful when-not condition. It does not name alternative sibling tools, but the exclusion is clear enough.

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

• dsh_find_sessionsA
  4.4/5.0
  Behavior5/5

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

  Annotations already declare read-only, idempotent, non-destructive behavior, and the description adds valuable limits beyond annotations: it returns no history/raw projections, filters never authorize automatic selection or attachment, and results are limited to bounded metadata. This gives an agent a precise behavioral contract.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Three tight sentences, front-loaded with the core operation and followed by filter semantics and a critical usage warning. Every sentence earns its place; there is no redundant filler.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a 7-parameter tool with no output schema and only 43% schema description coverage, the description covers the main purpose, key filters, return usage, and boundary behavior. It omits maxResults and includeBlank semantics, so it is not fully complete, but it is notably stronger than the median tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The description maps four semantic filters to parameters: exact/case-sensitive title matching (title/titleMatch), canonical cwd (cwd), idle state (idleOnly), and BridgeTask mapping (mappedOnly). However, schema coverage is only 43%, and maxResults and the opaque includeBlank are never explained. The description partially compensates but leaves real gaps.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb and resource: 'Read bounded metadata for existing root sessions from DSH session.list.' It then lists the exact filter dimensions and states what the tool does not return ('no history or raw projections'), which clearly separates it from session-history and attach-type siblings.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  It gives an explicit downstream directive: use the returned exact sessionId and precondition fields with dsh_attach_session, and never select a session by title alone. It does not fully enumerate when to prefer this tool over every sibling, but it gives strong context on how to consume the result.

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

• dsh_followupA
  4.4/5.0
  Behavior4/5

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

  The annotations show the tool is not read-only and not idempotent, but the description adds important behavioral context: the write is never automatically retried, and an attempted session.selectModel may persist as the DSH global default even when selection fails. This goes beyond what the annotations say, though it does not cover all possible side effects like auth failures or destruction.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is dense but well organized: core purpose first, followed by a guardrail about task IDs, then mode behavior, routing caveats, and retry semantics. Each sentence earns its place and there is minimal redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a write tool with no output schema and 8 parameters, the description covers the essential behavior needed to select the tool and make a correct call, including the no-guess rule, mode semantics, routing side effects, and no automatic retry. It is not fully complete because some non-required paramters like expectedRevision and sinceCursor remain semantically under-specified and the description does not mention what the agent should expect in return.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The description adds real semantics for mode and model routing: queue targets the next turn, steer targets the active turn's next step, and routing can be omitted to inherit the session route. However, schema description coverage is low at 38%, and parameters like sinceCursor and expectedRevision are not explained in the description, leaving gaps for an agent that needs to use them.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific action: continue the same known BridgeTask and root DSH session rather than creating a new delegation for the same work. It also gives a clear decision rule about known vs unknown task IDs, which helps distinguish the tool from sibling tools like dsh_delegate and dsh_continue.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly says when to use the tool, when not to use it, and what to do instead: never guess an old task ID and start a fresh delegation if no matching task ID is known. It also clarifies the queue and steer modes and the consequences of selection failure, leaving little ambiguity about correct invocation.

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

• dsh_continueA
  4.5/5.0
  Behavior5/5

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

  Although annotations provide no safety hints and idempotentHint=false, the description exposes non-obvious behavior: model routing is catalog-validated and re-read before the prompt, failure may skip the prompt but can still persist a selectModel global default, and 'the write is never automatically retried.' This is exactly the kind of behavioral context an agent cannot infer from the schema.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is dense but not bloated; every sentence contributes meaningful guidance. It front-loads purpose and task-id safety rules, then details routing and retry semantics. Minor structural improvement would be grouping routing caveats more cleanly, but the overall length is appropriate.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the absence of an output schema and the complexity of the tool, the description covers critical fallback behavior and model-routing pitfalls. It is not fully complete because it omits the meaning of sinceCursor/expectedRevision and any return-value guidance, which would matter to an agent trying to verify the tool's result.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is only 38%, and the description valuably annotates mode, model routing, and the task-id rule. However, key parameters such as sinceCursor and expectedRevision are never mentioned, and prompt is only implicit. The description partially compensates for the low coverage but leaves important gaps.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with 'Compatibility alias for dsh_followup' and specifies the exact operation: 'Continue the same known BridgeTask and root DSH session.' It also distinguishes this tool from creating another delegation, so an agent can clearly recognize its role relative to siblings like dsh_delegate.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  It gives explicit decision rules: use this when a matching task id is known, and 'start a fresh delegation when no matching task id is known.' It also clarifies mode boundaries ('queue targets the next turn; steer targets the active turn's next step'), which is strong guidance for correct invocation.

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