Sessy — AWS SES Observability

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the read-only safety is covered. The description adds useful context that rates are percentages of sends and that a daily series is optional, but it does not disclose deeper behaviors like pagination or result limits. This adds some value but not enough to exceed baseline.

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 exactly two sentences, front-loaded with the main purpose, and every clause carries value. There is no redundancy or filler, making it exceptionally concise and well-structured.

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 adequately enumerates the return components (counts, unique opens/clicks, rates, bounce breakdown, daily series). Combined with the fully documented input schema and safety annotations, the agent has sufficient information to select and call the 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 description coverage is 100%, so the schema already documents all five parameters. The description's mentions of 'one source or whole account', 'date range', and 'optional daily time series' map to parameters but add no new meaning not already present in the schema. Baseline 3 is appropriate.

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 states the tool aggregates email stats, enumerating specific outputs like counts by event type, unique opens/clicks, rates, bounce breakdown, and optional daily series. This verb+resource phrasing distinguishes it from siblings like get_message (single message) and search_events (event-level search).

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 provides clear context: aggregate stats for one source or the whole account over a date range. It does not explicitly name alternatives, but the scope and purpose imply when to use it versus siblings. Since there are no exclusions or when-not statements, it misses the top score.

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

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

Annotations already mark this as read-only and idempotent, but the description adds important behavioral details: it lists the exact return fields (subject, sender, destinations, SES tags, event timeline) and discloses the 500-event truncation behavior with the events_truncated flag. This goes well beyond the annotation hints and gives the agent a clear expectation of the response.

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 a single, well-structured sentence that front-loads the core purpose and packs essential details (return fields, truncation, paging) into parentheticals without excess. 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?

Despite having no output schema, the description fully specifies what will be returned and how to handle truncation. It gives the agent enough context to know exactly what to expect and what to do if the event list is incomplete, making it complete for a single-parameter read tool.

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% and the parameter already has a description ('SES message id from search_events results'). The tool description repeats the same provenance without adding new semantic meaning, so it scores at the baseline of 3.

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 'Fetch one email by its ses_message_id', which is a specific verb-resource pair that clearly distinguishes it from siblings like search_events (searching) and email_stats (aggregate stats). It also specifies the exact identifier source and the returned fields.

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?

Explicitly states 'from search_events results', informing the agent to first run search_events to obtain the ID. It also explains when to use search_events again for events beyond the first 500 (i.e., when events_truncated is true), providing clear alternative usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds useful behavioral context by specifying the return data (30-day health stats) and the workflow relationship to other tools. It does not mention ordering or pagination, but for a simple list tool with zero parameters, the disclosure is adequate.

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, front-loaded with the main action and output detail, followed by a clear usage directive. Every sentence earns its place, with no redundant or filler content.

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 zero-parameter, no-output-schema tool, the description is complete. It states what is listed (email sources), what each result includes (sent count, bounce rate, last event), and how to use the results (source_id for other tools). This is sufficient for an agent to select and invoke the 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?

There are no parameters in the schema, so the baseline is 4. The description does not need to explain parameters because none exist. It effectively communicates that the tool operates on the account's sources without requiring any input.

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 'List' with a clear resource 'email sources' and includes distinctive detail (30-day health stats with sent count, bounce rate, last event). It also distinguishes itself from siblings by noting it is the entry point and that other tools take a source_id from these results.

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 explicitly states when to use this tool: 'Start here: the other tools take a source_id from these results.' This clearly positions it as the first step in a workflow and implies that sibling tools should follow after obtaining a source_id. No exclusions are needed for such a straightforward list operation.

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

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

Annotations already declare readOnly, non-destructive, and idempotent hints. The description adds behavioral context: 'newest first' ordering, 'compact rows' return format, and the default 30-day date window. It also mentions the pointer to get_message for full detail, enriching understanding beyond the annotation-only safety profile.

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, front-loaded with the core purpose, then return behavior, alternative tool, and default behavior. Every sentence earns its place, with no redundancy or fluff.

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?

Given the tool's complexity (9 optional params, no output schema), the description covers essential context: what the tool searches, the compact return format, how to get full details, and the date default. It omits explicit pagination behavior, but the cursor parameter in the schema covers that. Overall, sufficient for an agent to invoke 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?

With 100% schema description coverage, every parameter is already documented. The description adds only a few clarifications (e.g., date_range defaults to last_30_days, mention of event type categories), but does not significantly go beyond schema-provided semantics. Baseline of 3 is appropriate.

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 states the tool searches email events and enumerates event types (sends, deliveries, bounces, etc.), with explicit 'newest first' ordering. It distinguishes itself from sibling tools by pointing to get_message for full timelines, making its unique role clear.

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 on when to use this tool (search events, compact rows) and explicitly names get_message as the alternative for full detail. It does not contrast with email_stats or list_sources, but the provided alternative is sufficient for common use cases.

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