wafeq_amortizations_preview_end_early_create

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds genuine value beyond these: it explains the method/semantics mismatch ('This is a POST, but Wafeq documents it as a simulation') and clarifies the side-effect profile ('writes nothing to the ledger'). This is useful context that annotations alone do not convey. It does not contradict 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 compact and front-loaded with the key discriminator ('READ-ONLY · preview / simulation'). There is minor redundancy: the title line 'Preview early termination' duplicates the header badge, and the endpoint line repeats the resource context. Overall, each paragraph earns its place, but the title repetition is unnecessary.

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, the description adequately conveys return value ('remaining balance and the posted events that would be reversed') and the no-side-effect guarantee. The schema covers the nested body parameters. The main completeness gap is the absence of explicit routing to the actual-termination sibling, which would help agents choose the correct tool when the goal is to execute rather than preview.

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 50%: date and start_date have schema descriptions, but id has none. The description adds only marginal parameter meaning by referencing 'the given date,' and id semantics are merely implied through the endpoint path '/amortizations/{id}/'. It does not adequately compensate for the undocumented id parameter beyond what the path suggests.

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: 'previewing the remaining balance and the posted events that would be reversed by terminating the amortization early.' The header line 'preview / simulation' and endpoint path 'preview-end-early' clearly distinguish it from the actual-termination sibling wafeq_amortizations_end_early_create and the creation-preview sibling wafeq_amortizations_preview_create. An agent can tell what this tool does without opening the schema.

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?

The description provides clear usage context: it is a simulation that 'returns the events that WOULD be generated and writes nothing to the ledger,' signaling when to use it (when a non-committal preview is needed). However, it never explicitly names the alternative for actually executing the termination (wafeq_amortizations_end_early_create), so the when-not-to-use guidance is implied rather than stated.

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