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

Even though annotations already declare readOnlyHint=true and openWorldHint=true, the description adds real behavioral detail: the result is a single instant (start == end), unresolvable phrases return candidates: [], and the agent must not fabricate dates or do its own date arithmetic. Nothing contradicts the annotations.

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 fairly long and restates some schema details, but it is well structured: purpose and examples first, then parameters, then response semantics, then anti-fabrication guidance. Every part earns its place, though a bit of trimming would make it tighter.

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 tool with no output schema and subtle semantics (timezone interpretation, vague phrases, single-instant result), the description is complete: it states the return shape, where the value flows (connections.time / departures.time), the empty-candidates behavior, and the required follow-up action. It also points to get_usage_guide for finer details.

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%, so the schema already documents all four parameters. The description adds meaningful operational semantics beyond that: text is marked as Pflicht, tz default is explicitly tied to Europe/Berlin local-time interpretation, and format is labeled as something the agent should leave out. This is more than the baseline needed for full schema coverage.

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+resource construction: "Löst eine Zeit-Nennung in einen absoluten ISO-8601-Zeitpunkt auf" and then gives concrete examples like "morgen früh" and "in zwei Stunden". It also states a clear boundary against a sibling scenario (full ISO-8601 with offset needs no call), so an agent can tell exactly what this tool does.

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 says when to invoke (any time mention), when not to invoke (user already gave a complete ISO-8601 timestamp with offset), and points to get_usage_guide for the ambiguous-time case. It even instructs the agent to use this tool as the canonical source for "now" instead of inventing a date, which is strong usage guidance.

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