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

Annotations already declare a safe, idempotent, closed-world read, so the bar is lower; the description still adds real behavior beyond them — the reporting flag's effect on fiscal-year allocation, that unknown actual values and reporting-calendar evidence are retained in rows and summary, and that the endpoint returns the complete scoped set rather than a page. No return schema exists, and only the row/summary shape is touched on briefly.

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 first clause restates the title verbatim, the phrasing 'GET query year is required' is garbled, and a double period plus operation-ID/describe_operation boilerplate pad the end. The genuinely useful guidance (year bounds, reporting semantics, complete-rows behavior) is present but not cleanly 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 read-only portfolio aggregate with no output schema and a fully opaque query object, the description supplies the essentials an agent needs: required year, the reporting switch, optional narrowing keys, and confirmation that the full scoped set is returned. The one loose end is that the schema marks no parameters as required while the description insists year is required.

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% and the schema itself is an opaque free-form 'query' object, so the description carries the full burden and mostly succeeds: it documents year (required, bounds 1900–2200), reporting (boolean with a specific fiscal-calendar effect), and leaseId/termId (scope narrowing). It does not show how these keys are actually passed inside the untyped query object.

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 states a specific resource and its scope: portfolio-level gross sales estimates, actual sales, and supplemental rent obligations, which implicitly distinguishes it from the many lease-scoped supplemental-rent siblings (get_leases_by_leaseId_supplemental_rent_*). It never explicitly names an alternative tool, so the differentiation is inferred from the word 'Portfolio' rather than stated.

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 concrete calling context: 'year is required (1900–2200)', the meaning of reporting=true versus the default contractual source periods, and that leaseId/termId narrow scope. It also rules out a wrong expectation ('not a paginated lease list'). It stops short of naming a sibling to use instead when a single-lease view is wanted.

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