session_bind

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

With no annotations provided, the description fully discloses the HMAC verification process, trust_level ceiling, return values, and post-binding logging/enforcement behavior. It also explains the operator/CLI-only secret registration and the sudo invariant, giving a complete safety profile.

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 relatively long but front-loaded with the primary action. Each sentence adds security-critical detail; the parenthetical quote about 'Elder' reinforces the ceiling concept. It is dense but not wasteful.

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?

Despite having no output schema, the description specifies the exact response shape ({session_id, agent_id, trust_level, tier} or {error}) and the two modes (log vs enforce). It covers all necessary input constraints and security prerequisites, making it sufficient for correct invocation.

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 schema provides only raw names/types (app_id string, header object), but the description explains that header must be a 13-field HMAC-signed object with agent_id equal to app_id and trust_level capped at the registered ceiling. This adds critical semantic constraints that the schema lacks (0% coverage).

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 'Open a cryptographically-bound session (check-in)', which states a specific verb and resource. It clearly distinguishes itself from sibling session tools (session_read, session_enter) by emphasizing cryptographic binding and the check-in mechanism.

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 implies that binding must occur before subsequent calls ('Once bound, the tier is LOGGED on your subsequent calls') and explains an enforcement mode. However, it does not explicitly name alternative tools or provide concrete 'when to use vs. session_enter' guidance. The sudo invariant does tell users what cannot be done via MCP, giving a partial exclusion.

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