chamber_ask

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

Annotations declare readOnlyHint=false/idempotentHint=false, and the NOTE goes well beyond them: it spells out the commit gate, that verified claims become beliefs with pins, that unsourced assertions mint citation debt, that spend is recorded, and what it cannot do (bypass the gate, activate a skill, approve a pending write). This is unusually rich disclosure for a write tool.

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?

Purpose and the routing alternative are front-loaded, and the return semantics (ALLOWED/UNSUPPORTED, file#passage refs) come before the NOTE. The NOTE is long but each clause carries distinct behavioral information; slightly dense rather than 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?

With no output schema, the description still explains return values (ALLOWED vs UNSUPPORTED and their meaning, openable file#passage references) and the corpus-only limitation. For a write tool with non-idempotent semantics, the commit-gate and side-effect disclosure makes it complete.

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 description coverage is 100%, so exact/semantic/strict are already documented in the schema (including that semantic contradicts exact). The description's mention of citation-debt minting and strict refusal adds context for strict's effect, but it does not add syntax or format meaning beyond the schema; baseline 3 applies.

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?

States a specific verb+resource (have Chamber's configured model answer a question from the user's notes) plus the scope (only from the indexed corpus). It explicitly names the sibling it is not (chamber_check) and distinguishes the check-your-own-answer case, so an agent can route without opening a schema.

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?

Explicit routing: 'To check an answer you wrote yourself, use chamber_check instead,' plus a stated boundary ('Answers only from the indexed corpus; says so when nothing matches'). When-to-use, when-not, and the named alternative are all present.

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