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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered without the description. The description adds a governance note that MCP approval requirements are org-configurable while business workflow approvals always apply, which is real added context, but it is vague about whether that affects this read call. It says nothing about result size, pagination behavior, or what 'metadata' excludes.

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?

Three sentences, of which only the middle one carries tool-specific meaning; the first is organizational boilerplate and the third is approval-policy boilerplate. The actual purpose statement is buried in the middle rather than front-loaded, though no sentence is long-winded.

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 need not be described, and annotations cover safety, lowering the burden. Still, an agent gets no information on what scoping is required, what 'search' does, or how results are ordered and paged — gaps that matter for a four-parameter list tool on a large tenant.

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 four parameters, and the description mentions none of them. The required siteId is never explained, and the semantics of search (which fields it matches, and how it interacts with siteId scoping) and of limit/offset paging are left entirely to convention. With zero coverage the description should compensate and does not.

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 sentence 'Read closeout document metadata' states a specific verb (read) and resource (closeout document metadata), making the operation identifiable. It does not, however, distinguish this listing tool from the sibling get_closeout_document (single-record fetch) or list_site_documents, so the listing-vs-fetch boundary is left implicit.

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 only usage cue is the boilerplate 'Use this when working with RetailHardHat field_operations records in the connected organization', which is generic context rather than a condition for selecting this tool. No alternative is named and no exclusion is given (e.g. when to use get_closeout_document instead, or whether siteId scoping is mandatory for a meaningful result).

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