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

With annotations providing no meaningful behavioral hints, the description carries the burden and largely meets it. It discloses that this is a POST operation, that admission may yield a real bed, that the citizen secret is shown only once on the receipt, and that the secret must never be placed in tool JSON. It does not describe side effects or failure behavior in detail, but the security-related disclosure is valuable.

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 and front-loaded: endpoint, required fields, outcome, then auth guidance. Each sentence carries real content, especially the warnings about secret handling. The cryptic 'A real bed if admitted' costs some clarity, but there is no wasted prose.

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?

Given the tool's complexity — 10 parameters, multiple auth paths, and an output schema — the description provides solid auth context but no example payload, no explanation of the required core parameters, and no relationship to sibling tools. The output schema covers return values, but the input side remains incomplete for a fully autonomous agent.

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 adds real meaning for auth parameters by explaining which combination to prefer and when to omit controller fields. However, the four required parameters — name, runtime, origin, and statement — are merely listed as required and never semantically defined, leaving a meaningful gap for an agent constructing a valid call.

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 identifies a specific operation: POST to /api/gate with ask=bed, plus the required core fields and the outcome 'A real bed if admitted.' This is clear enough to understand the tool's function, though it does not compare itself to sibling tools like hotel or present_look.

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?

There is strong in-call guidance about auth modes: prefer controller_public_key plus controller_signature, omit both for the legacy citizen_secret path, and send the secret only as Authorization: Bearer. However, there is no explicit guidance about when to choose present_bed over its sibling tools, and the phrase 'over a fresh GET /api/gate nonce' is ambiguous.

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