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

Goes well beyond the annotations by disclosing the €30 hold, its 7-day duration, the no-charge-until-mutual-accept rule, the no-show forfeiture and show-up credit, and that the call only stores a proposal with a review link in the result. That is exactly the financial and side-effect context an agent needs before invoking a non-readOnly, non-idempotent 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?

No filler sentences — every clause carries pricing, format, or lifecycle information — but the opening is a sentence fragment with the object before the verb, and pricing, format, and confirmation semantics are crammed into run-on sentences. The most important thing (what the tool does) is not front-loaded.

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 mutation tool with no output schema, the definition covers the action, constraints, financial side effects, and the post-call confirmation flow, plus a hint that the result contains a review link. It omits repeat-invocation behavior (idempotentHint is false) and what happens to the hold at day 7, which an agent might need.

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?

With schema coverage at only 25% (only summary is documented in-schema), the description carries the load for slots — ISO 8601, weekdays, on the hour, 09–18 CET, 3–10 business days out — far exceeding the schema's bare minItems/maxLength. appId is explained only loosely ('the person's own brief (appId)') and the note's 400-character cap is left to the schema, so it stops short of full compensation.

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?

States a specific action (propose a 30-minute call on a pitch tied to the person's brief via appId) with the required artifact (3+ concrete slots, optional note). It implicitly separates itself from propose_booking_accept by stating 'Stores a proposal only', but never names the sibling and the opening is a dangling fragment that delays the verb.

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?

Establishes clear context: use this as the client of a pitch on a brief, and only this side initiates the proposal. It clarifies that nothing is committed until the other party confirms on welance.com/directory, which steers an agent away from treating it as a confirmation step, but it never explicitly names propose_booking_accept as the follow-up tool.

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