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

Adds substantial context beyond the readOnly/idempotent annotations: VOIDs are excluded unless include_voids=True, performance degrades on 90+ day windows (roughly 5800 rows per 30 days, 1-3 minutes), and follow-up queries are cached for 5 minutes. Unreachable Locations are reported as skipped, which tells the agent how to interpret partial results.

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?

Front-loads the resource identity and window, then details behaviors, then parameters. Every sentence is substantive, though the location paragraph is denser than the rest and could be trimmed slightly for an all-defaults call.

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?

An output schema exists so return values needn't be specified, and performance, caching, void handling, and multi-location behavior are all covered. The remaining gap is the undocumented meaning of portfolio and property_ids relative to location, which an agent could misresolve when filtering.

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 0% across 7 parameters, so the description carries the burden. It explains location thoroughly, include_voids, and the trailing-30-day default for the date window, but top_n, portfolio, property_ids, and the start/end date format go unmentioned, leaving half the surface undocumented.

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 verb and resource ('Vendor spend / AP outflows') plus the report source (PayablesByAccount, 183) and enumerates what it surfaces: top vendors by gross spend, per-property totals, largest individual bills. That output shape clearly separates it from siblings like get_bills (raw records) or analyze_aged_payables.

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 gives the default window (trailing 30 days) and detailed guidance on the location parameter (single ID, comma list, or "all"), plus the caveat to pass the location when filtering by IDs. But it never says when to choose this over get_bills, analyze_aged_payables, or vendor_compliance, so the when-to-use decision is left implicit.

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