session_bind

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

Annotations (readOnlyHint=false, destructiveHint=false) indicate a state-changing but non-destructive operation. The description discloses that binding a session logs the tier on subsequent calls (`bind_observed`) and may enforce per-call signatures with `WILLOW_MCP_ENFORCE_BINDING`. It also details that secret registration/rotation is operator/CLI-only. This adds significant behavioral context beyond the annotations, covering side effects, dependencies, and constraints.

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 dense but well-structured: the first sentence states purpose and core requirements, the second explains consequences and environment dependencies, the third clarifies operator-only secret management. Each sentence earns its place, and the most critical information is front-loaded. No redundant 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?

For a tool of this complexity (HMAC signing, trust ceilings, enforcement mode), the description covers all essential aspects: purpose, prerequisites, return values (session_id, agent_id, trust_level, tier or error), side effects on subsequent calls, and external dependencies. The lack of an output schema is compensated by explicit return descriptions. Nothing an agent needs to call it correctly is missing.

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 provides meaningful semantics for both parameters. For `header`, it specifies a 13-field HMAC-signed object with `agent_id` matching `app_id`, and explains the trust_level capping. `app_id` is implicitly understood as the identifier used in the header. Given 0% schema description coverage, this is a substantial addition, though it does not enumerate every field.

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 clearly states the action: 'Open a cryptographically-bound session (check-in).' It specifies the resource (session), the action (open/bind), and the key condition (cryptographically-bound). It differentiates itself from sibling session tools by emphasizing the required HMAC-signed header and trust-level capping, making it distinct from session_enter or session_read.

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?

The description provides clear context on when to use this tool: when a cryptographically-bound session is needed, with explicit prerequisites (13-field header, agent_id equals app_id, operator-registered secret). It explains the verification and ceiling mechanism, but does not explicitly name alternative tools or state when NOT to use it. This is clear context without explicit exclusions.

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