Add a responder to a JSM alert

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

Goes well beyond the annotations by disclosing that the action is asynchronous and must be verified via jsm_get_request_status with the returned requestId, that responders are additive, and the specific failure mode (HTTP 422 / failed status means responder_id doesn't exist or has the wrong type). No contradiction with idempotentHint=true or readOnlyHint=false.

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?

Well-structured and front-loaded with the core purpose, followed by labeled sections for Args, Returns, async warning, example, and error handling. The Args section partially duplicates the fully-documented schema, which is mild redundancy, but every other sentence earns its place and the headers make scanning efficient.

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 mutating, asynchronous tool this is as complete as it gets: it documents the return shape (requestId enabling follow-up), names the follow-up tool, explains the failure mode, provides a usage example, and tells where to source valid IDs. Nothing an agent needs to invoke it correctly is missing.

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 100%, so baseline is 3. The description adds genuine value beyond the schema: the example maps natural-language intent ('Page the database team on this') to responder_type, and the error-handling section clarifies what a wrong responder_id/type produces behaviorally. The Args block itself is largely redundant with the schema, limiting the additional credit.

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 uses a specific verb-resource pair ('Add a responder... to an existing JSM alert') and names the four entity types the responder can be. The additive scoping note ('does not remove the existing ones') helps distinguish it from assignment-style siblings, and the stated outcome (notified and accountable) makes the effect concrete.

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?

It gives a clear when-to-use signal: 'pull in another team once triage shows the alert belongs elsewhere.' It also routes the agent to jsm_get_request_status for async verification and jsm_list_schedules for finding IDs. It does not explicitly name alternatives to avoid (e.g., jsm_assign_alert), but the additive-vs-replace distinction serves that role implicitly.

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