zeph_ask

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

Annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description goes well beyond these: it reveals that the call blocks until user response or timeout, that attached files arrive as local absolute paths in the result's `attachments`, and that the channel is not end-to-end encrypted. It also notes the requirement for ZEPH_HOOK_ID. These are material behaviors not captured by annotations, and none contradict them.

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 five sentences, each earning its place: purpose, primary usage pattern, blocking behavior, prerequisite, and a security caveat. Critical constraints (actions guidance, secret caution) are front-loaded. There is no fluff or repetition of schema fields, keeping it tightly scoped yet comprehensive.

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 an interactive, blocking tool with encryption limitations and attachment handling, the description covers everything an agent needs: how to frame the question, when to pass actions, timeout behavior, the hook requirement, the attachment result format, and the security posture. The schema documents every parameter, and the description fills in behavioral details like blocking and result shape. No critical omissions remain.

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 the baseline is 3. The description adds meaningful usage context, especially for `actions`: it explains that actions are quick-reply buttons, that they should carry next-step candidates plus a 'Done-like' fallback, and when it is acceptable to omit them. It also clarifies that attachments are part of the answer, which informs how the result should be interpreted. This is more than a restatement of the schema, hence a 4.

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 a precise, verb-first statement: 'Ask the user a question on their phone: quick-reply buttons plus a text field — they tap or type.' It clearly identifies the resource (the user's phone interaction) and the action (ask). It also distinguishes itself from siblings by explicitly contrasting with zeph_notify/zeph_file over encryption, and through the quick-reply behavior that zeph_notify lacks. The purpose is unambiguous and differentiated.

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 when‑to‑use instructions are given: 'Pass `actions` (2–4 buttons) unless the answer is free-form text.' It also states the blocking behavior ('Blocks until they answer or `timeout` passes'), the prerequisite ('Requires ZEPH_HOOK_ID'), and a caution about content secrecy because it is not end-to-end encrypted. The input schema for `actions` reinforces this with guidance on what to include and when to omit, so an agent knows exactly how to invoke this tool versus alternatives.

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