create_nk_letter

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

With no annotations provided, the description carries full burden for behavioral disclosure. It reveals side effects ('Also files the unit trail and a settlement'), server-side sanitization ('the server strips them'), and an overwrite risk ('so this letter does not overwrite the other stay'). This is substantial, useful transparency even though auth or rate-limit details are absent.

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 dense but not bloated. It front-loads the primary purpose and then adds necessary constraints and side-effect warnings. Every sentence carries operational or safety-relevant guidance, though the paragraph is longer than strictly minimal and could be split for easier parsing.

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 complex tool with 11 parameters and no output schema, the description covers the core behavior, critical constraints, and side effects well. However, it leaves the relationship between the 'createSettlement' parameter and the stated 'files a settlement' behavior unclear, and it does not address return format beyond 'Returns a PDF.' These gaps keep it from a 5.

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 only 18%, so the description must compensate. It does add meaning for 'items' (recoverable line items only), and for occupancyId/periodFrom/periodTo (prevent overwriting when tenants changed). However, it does not explain optional parameters like prepaidEuros, createSettlement, title, greeting, or notes, leaving significant gaps for a tool with 11 parameters.

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 opens with a specific verb-resource pairing: 'Compile a tenant Nebenkostenabrechnung PDF on the Achi server.' This clearly identifies what the tool produces and distinguishes it from sibling tools like list_nk_settlements or update_nk_settlement, which operate on existing settlements rather than generating a new letter.

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 gives explicit instructions on when to pass certain parameters: 'If tenants changed mid-year, pass occupancyId + periodFrom + periodTo.' It also provides exclusions ('Do not include Eigentümerkosten leftovers or Quellenangabe') and input constraints ('Pass recoverable line items only'). No alternative tool is named, but the conditions for correct use are clear.

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