aws_refresh_if_expiring_soon

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

The description goes well beyond the annotations by disclosing that status: 'ok' is a point-in-time reading, not a lease, and that no re-check happens afterwards. It also clearly states the side effect of triggering aws_login_start and returning a verification URL and code, which is essential for understanding the tool's behavior.

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 description is moderately sized but every sentence earns its place: it states the core behavior, the conditional outcome, the recommended use case, and a crucial caveat. It is front-loaded with the main purpose and avoids unnecessary filler.

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?

Given there is no output schema, the description does a good job covering return values (verification URL + code, or status: 'ok' with minutes left) and failure implications. It could have benefited from explicitly stating that the returned verification URL requires user interaction to complete login, but overall it is complete enough for safe invocation.

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 baseline is 3. The description adds meaningful extra semantics for thresholdMinutes by explaining how to set it relative to workflow length and warning that 'ok' is not a guarantee. This is valuable beyond the basic schema definitions.

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 clearly identifies a proactive SSO token check with conditional refresh behavior, and names the resource (cached token) and side effect (kicks off aws_login_start). It doesn't explicitly name a sibling alternative it should be distinguished from, but the mechanism is clear enough that an agent can tell it apart from direct login or identity-check tools.

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 description gives explicit when-to-use guidance: 'Use at the start of a multi-step AWS workflow to avoid mid-session expiry.' It also explains how to adjust thresholdMinutes to cover workflow length. It doesn't explicitly list alternatives not to use, but the context strongly implies this is a preliminary check before other AWS calls.

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