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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered; the description adds genuinely new behavioral facts on top — the computation is deterministic, concessions are amortised straight-line over each lease term, leases ended before as_of are treated as month-to-month, warnings may be returned and should be surfaced, and the formula id calc.multifamily_rent_roll@1 should be cited. The 'can be long' note on the per-unit table also warns about output size, which is useful given there is no output schema.

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?

It is a single dense paragraph, front-loaded with the resource and scope, and nearly every clause carries real information (limits, statuses, outputs, determinism, citation requirement). It is slightly over-stuffed: the concession-type parenthetical and the output list duplicate schema content and make the block harder to scan than a short bulleted split would.

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, nested-input analytical tool with no output schema, the description does the heavy lifting by naming the metrics returned and the two input modes, and it warns about warnings and output length. Remaining gaps are minor — nothing about error conditions or what shape the warnings/steps take — but nothing critical to calling it correctly is missing.

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 100% and the nested concession oneOf branches are fully documented with examples, so the schema carries the parameter burden. The description reinforces the units-vs-lease exclusivity (up to 5,000 units) and the three concession forms, but adds little meaning the schema does not already state — baseline 3 is appropriate.

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 and resource ('Analyze an apartment rent roll') and then enumerates the exact outputs — gross potential rent, loss to lease, amortised concessions, physical/economic occupancy, expiration schedule, per-unit-type summary — plus a distinct single-lease mode. That enumeration makes it unmistakable against siblings such as calc_net_effective_rent, calc_walt, or calc_rent_schedule without opening any 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?

'Deterministic: use this instead of doing the math yourself' gives a clear rule for choosing this over manual reasoning, and 'Single-lease mode (lease instead of units)' signals the two input modes. However, it never names an alternative or a when-not condition, so an agent facing a single-lease effective-rent question cannot tell from this text whether calc_net_effective_rent is the better pick, and there is no guidance on when a rent-roll analysis is inappropriate.

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