get_system_event_history

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

With no annotations provided, the description carries the full burden. It discloses that the tool returns a newest-first event list with specific fields (id, history_type, status, summary, completed). It mentions the input parameters and their defaults, but does not describe edge cases like system not existing (though it does handle name not found via resolution). Overall, it gives sufficient behavioral insight for a read-only listing tool.

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 yet informative, using five sentences to convey purpose, inputs, error handling, return format, and alternative tool. Every sentence adds value without redundancy.

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 absence of an output schema, the description adequately specifies the return format (newest-first list with five fields). It covers pagination parameters, error resolution, and sibling tool alternatives. For a list tool with 4 parameters, it is complete.

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 0%, so the description must compensate. It explains that system_identifier can be system_name or system_id, and that offset, limit, and earliest_date are optional. It also provides guidance on resolving name not found. However, it does not specify the format for earliest_date, which could be ambiguous. Still, it adds significant meaning beyond the sparse schema.

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 'List events for one system,' specifying the action and resource. It distinguishes itself from sibling tools like get_system_event_details, which is for a single event, and other system listing tools.

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 provides explicit when-to-use guidance: it lists events for one system, and advises using get_system_event_details for individual events. It also includes error handling steps: if the system identifier is a name not found, resolve with find_systems_by_name.

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