Recent SIP events

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

The annotations already mark this as read-only and idempotent, but the description adds valuable non-obvious context: the data is a volatile in-memory ring buffer rather than durable history, and a `sip_trunks:read` scope is required. This is meaningful behavior disclosure beyond what annotations alone provide.

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 compact and front-loaded, with each sentence earning its place: what the events are, the ring-buffer caveat, the polling instruction, and the required scope. No filler or redundant restatement.

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 read-only tool with no output schema, the description covers event types, data volatility, auth requirements, and pagination. The main gaps are the precise role of the `id` parameter and the effect of `limit`, but those are minor against an otherwise thorough description.

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 useful meaning to `since_id` by tying it to `last_id` from the previous response. However, the required `id` parameter is ambiguous—the tool name implies a SIP trunk ID, but the description only refers to 'recent events for this account'—and `limit` is not explained beyond schema constraints.

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 clearly identifies the resource (SIP engine events for the account) and the specific event content: registration, call setup, and carrier rejections with causes. This distinguishes it from sibling SIP trunk configuration/status tools, which are about trunk state rather than recent event logs.

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 explicitly describes the polling pattern: 'Poll with since_id set to the last_id of the previous response to get only new entries.' It also warns that this is a live in-memory ring buffer, not an audit trail, which tells agents when not to rely on it. It doesn't name an alternative tool, but the usage context is clear.

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