handshake_get

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses a critical non-obvious behavior: every read is written to an append-only audit log with the reason, and warns users to pass a truthful reason. This goes well beyond a simple 'read' and reveals the side-effectful nature of the operation.

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 two sentences with no wasted words. The core action is front-loaded ('Read ONE credential by name'), followed immediately by the prerequisite and the behavioral caveat. Every clause earns its place.

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 simple read-by-name tool with three required parameters and no output schema, the description covers the essential contextual basis: what it does, the session prerequisite, the audit-log side effect, and how to supply the reason. Combined with the schema's parameter descriptions, an agent has enough information to invoke this tool correctly.

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 coverage is 67%: name and reason are described in the schema, but session is not. The description adds important semantics by stating it 'Requires an open session token' and re-emphasizing that the reason is recorded permanently. This compensates for the schema gap on session and reinforces the meaning of reason.

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 states a specific verb and resource: 'Read ONE credential by name.' The emphasis on 'ONE' clearly distinguishes this from handshake_list, which would be the sibling for reading multiple credentials. This makes the tool's purpose unambiguous.

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 gives clear context for using the tool: read a single named credential, requiring an open session token and a truthful reason because of audit logging. However, it does not explicitly state when not to use this tool or name alternatives like handshake_list for enumeration, leaving some routing to inference.

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