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

With no annotations at all, the description carries the full behavioral burden — and it delivers. It discloses the tool is free, enumerates all six lifecycle states, reveals that paid tools fail while free tools remain available in failure states, explains the root causes (permanent SQL errors, Neon HTTP 402 quota exhaustion), and states that retrying will not help for misconfigured and quota_exceeded. This is far richer than a typical status-tool description and gives the agent real operational understanding.

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 lead sentence delivers the purpose in three words, and each list item earns its place: state name, meaning, consequence, and recommended action. The single-word 'Free.' conveys a cost fact that would otherwise be missing. The bulleted structure is scannable and every sentence adds distinct information with zero 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?

The tool has zero required parameters and an output schema, so return-value details are already covered by structured data. The non-obvious operational complexity — the six lifecycle states and their downstream effects on other tools — is fully enumerated with remediation guidance. Nothing an agent needs to correctly interpret and act on this status check is missing.

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 100%, so the description need not compensate. The single optional patron_npub parameter is fully documented in the schema, including its effect (adding an upstream_oauth block with stored token expiry) and the proactive-refresh rationale. The description itself adds no parameter detail, which is acceptable at this coverage level; baseline 3 applies.

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 opening line 'Check operator readiness' names a specific verb and resource, and the lifecycle-state enumeration defines exactly what the tool reports and the actionable meaning of each value. It is clearly distinguishable from siblings like taxsort_service_status and taxsort_session_heartbeat by being specifically about operator lifecycle readiness, though it never names those alternatives explicitly.

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?

Every lifecycle state carries an explicit directive: 'Proceed with tool calls,' 'Try a tool call — it will warm up on demand,' 'Call register_operator first,' and 'retrying does NOT help' for the two permanent-failure states. It also routes the agent by distinguishing free vs paid tool availability per state. However, it does not explicitly state when to choose this tool over sibling status tools, so it stops short of full when/when-not guidance.

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