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

Annotations already declare readOnly, non-destructive, open-world, so the safety profile is covered. The description adds real context beyond them: the auth requirement (Cotlet API key with access to this app), what each selection contains, and the behavior of the status default ('the selections still waiting on the client').

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 and return shape, then scoping, then the status default, then auth. Efficient overall, though 'Each selection lists its options, the allowance and its status' mildly restates the opening sentence.

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?

With no output schema, the description carries the burden of describing returns, and it does so (options, allowance, status) while also covering auth and default filtering. Complete enough for an agent to invoke correctly; minor gap is no note on pagination or volume.

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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains the empty-job_id semantics (all open jobs) and interprets the 'pending' enum value as selections awaiting client action, which is domain knowledge not present in the schema.

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 ('List selections') and enumerates what each record contains (options, allowance, approval status), which clearly distinguishes it from the sibling mutation buildertrend_approve_selection_choice. An agent can tell what this returns without opening the 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?

Gives clear scoping context: one job via job_id, or all open jobs when job_id is empty, plus the default status of pending. It does not explicitly contrast with siblings or state when-not-to-use, but the retrieval context is unambiguous.

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