seal_get

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description reveals meaningful behavior: state value semantics, the unknown-intent behavior returning {error: 'unknown intent'} rather than a hard error, and the explicit statement 'Changes nothing'. This is rich, non-obvious behavioral context.

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 compact and front-loaded: the primary purpose appears first, followed by essential return-field and state semantics, then routing guidance. Every sentence contributes information, and there is no redundant fluff.

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 compensates well by listing the returned fields, explaining state values, describing the unknown-intent response, and clarifying the tool is read-only. It also disambiguates against closely related sibling tools. An agent has enough to call this tool correctly and interpret its output.

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 input schema already fully documents the single parameter with 100% coverage, including where the intent id comes from. The tool description only echoes the idea of 'one intent' and does not add meaning beyond the schema, so the baseline of 3 is appropriate.

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 states a precise verb and resource: 'Read-only status of one intent', and enumerates the exact fields returned. It also differentiates itself from sibling tools by naming seal_verify and seal_incident_receipt as alternatives for different needs.

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 clearly establishes that this tool is for checking the status of a single intent and explicitly points to seal_verify for the whole chain and seal_incident_receipt for auditor-grade exports. It does not enumerate every exclusion scenario, but the contextual guidance is clear and actionable.

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