Intent status

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

The annotation readOnlyHint=true already covers safety, so the description does not need to restate read-only behavior. It adds information about return contents ('cancel window and tx hash when finalized'), which is useful context about what the operation yields, but it does not disclose edge-case behavior such as unknown/nonexistent intent handling. This is acceptable given the annotation coverage.

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?

Two short sentences deliver the essential information with no filler. The core action and status vocabulary are front-loaded, and the extra detail about tx hash and cancel window is appended without clutter. Every word earns its place.

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 appropriately lists the possible statuses and notes extra fields for finalized intents. This gives an agent a working mental model of the result. The only minor gap is the vague 'cancel window' term, which is not defined, but overall the description is sufficiently complete for a low-complexity, single-parameter read-only tool.

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?

The schema's only parameter, intentId, has no description, and the tool description does not add explicit parameter semantics beyond the obvious meaning of the parameter name. With schema description coverage at 0%, the description technically should compensate, but because there is a single self-explanatory parameter, the gap is not severe. The phrase 'Get intent status' reinforces that intentId identifies the intent.

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 uses a clear verb-object structure ('Get intent status') and enumerates the possible status values, which makes the tool's purpose immediately understandable. It does not explicitly differentiate itself from siblings like cims_list_intents, but the focused status vocabulary suggests a single-intent lookup rather than a list operation.

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?

Usage context is only implied: the tool is for checking the status of a specific intent identified by intentId. There is no explicit guidance on when to prefer this over cims_list_intents or cims_resolve, nor any exclusion criteria. The status list gives a hint, but the description does not directly address alternative selection.

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