Get an activity's event history

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

The readOnlyHint annotation already establishes that this is a safe read, so the bar is lower. The description usefully adds the data-model insight that events accumulate on every state transition. It says nothing about ordering, pagination, or result size, so it is adequate but not rich.

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 core action is front-loaded in the first sentence, and the rationale follows efficiently. The middle sentence ('Activity gets event record every time it transitions to a new state') reads slightly awkwardly and repeats the transition idea, but the length is reasonable for the information conveyed.

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 single-parameter read tool with no output schema and full schema coverage, the description supplies enough to call it correctly and understand why it exists. Missing return-shape and ordering details are minor since no output schema is provided and could reasonably be discovered at call time.

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 is a single required parameter whose meaning ('Id of the activity to retrieve events for') is fully documented in the schema at 100% coverage. The description adds no syntax, format, or sourcing detail beyond that, so baseline 3 applies.

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 states a specific verb and resource: retrieve the event history for a given activity. It also explains what an event is (a record created on each state transition), which gives the agent a concrete mental model. It does not, however, explicitly distinguish this from siblings like get_activities_information, which could be confused with it.

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 reason to use this tool: since an activity only stores its current state, the event history is needed to learn how it got there. That is usable context for selection. It stops short of naming an alternative or stating explicit exclusions, so it is not a full when/when-not treatment.

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