mailkite_list_enrollments

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

Annotations declare readOnlyHint=true, and the description is consistent ('List who...'). It adds the prerequisite of a live API key and the ability to filter by status, which are not conveyed by annotations or schema. The mention of a status filter is a behavioral trait, though it is not reflected in the schema, creating a minor inconsistency.

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?

Two short sentences that immediately state the core purpose and the key actionable detail (status filter). No filler or redundancy; the structure is front-loaded with the primary action.

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 tool it is fairly complete, but the status filter mention without a corresponding schema property is a notable gap. It also does not describe what the output will be (though no output schema exists). The API key requirement is useful context. The mismatch between description and schema lowers completeness.

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 schema description for the single parameter is uninformative ('Path parameter id'), but the description partially clarifies that id refers to the sequence. However, the description also references a status filter that is not a parameter in the schema, which could mislead an agent into passing an unsupported argument. It adds some meaning but with inconsistency.

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 action ('List who is in a sequence') with a clear resource (enrollments in a sequence) and the kind of data returned ('where each of them is'). This precisely distinguishes it from siblings like get_enrollment, cancel_enrollment, and list_enrollment_runs.

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 clearly implies the use case: enumerate enrollments in a sequence, optionally filtered by status. It does not explicitly contrast with alternatives, but the phrasing 'in a sequence' and the filter mention provide sufficient contextual guidance for an agent to select it over get_enrollment or list_enrollment_runs.

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