get_timeline_markdown

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

With no annotations, the description carries the behavioral transparency burden. It discloses non-obvious behavior: the output is a combined Markdown timeline across three event types, ordered chronologically, and limited to one app's events when app is provided. It does not spell out all optional-filter effects, but the read-oriented content and 'get' verb make the read-only nature reasonably clear.

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 three crisp sentences with purpose front-loaded, usage guidance second, and app scoping last. Every sentence earns its place, and there is no filler, repeated schema information, or boilerplate.

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?

An output schema exists, so return-value shape doesn't need to be in the description. However, all 5 parameters are optional with no schema descriptions and no annotations, and the description leaves limit, since, and channels ambiguous. It is excellent for purpose and routing but not complete enough for fully informed invocation across all parameter combinations.

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 for all 5 parameters. It clarifies the app parameter ('With app, only that app's events') and hints at test context, but limit, since, and channels receive no explanation. An agent would have to rely on parameter names and defaults to infer their semantics.

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 a specific verb and resource: it retrieves the full timeline as Markdown, listing messages, webhook_events, and stripe_events in chronological order. It also differentiates from get_message_detail by noting that the sibling covers only a single event's detail. An agent can confidently identify what this tool returns.

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 instructs to call this tool first when verifying a test result and names the alternative tool with the condition for using it: get_message_detail only for a single event's detail. The app-filter sentence adds clear guidance on when the tool is scoped. This is strong routing guidance.

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