Insurance coverage

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

Annotations already establish a safe read (readOnlyHint=true, openWorldHint=false) and the description does not contradict them. Beyond that it adds real behavioral context: limits live in the app rather than being passed in, amounts are in cents (so values are minor units, not dollars), and the result is empty when no limits are configured — an important edge case an agent would otherwise misread as an error.

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?

A single dense paragraph that front-loads the core action and its output shape before the disambiguation and the edge-case note. Some nested parentheticals make the middle clause heavy, but every sentence carries information — there is no 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?

No parameters and no output schema, so the description carries the burden of explaining what comes back, which it does (per-limit comparison, shortfall, unvalued-item count). Coverage is good for a zero-arg read tool; only fine details of the result structure are left implicit.

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 tool takes no parameters, so there is nothing for the description to disambiguate and the baseline is a 4. The note that amounts are in cents is the only "input-like" detail, and it is present.

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+resource: checks the household's insurance limits (contents cover, category/tag limits like jewelry or firearms) against inventory values. It names the exact outputs produced (limit vs. worth, shortfall, count of items with no recorded value), which makes it unmistakable against siblings such as inventory_report.

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 an explicit trigger phrase ("are we insured enough?") and explicitly routes the alternative case — total worth by room or property — to inventory_report. It also notes the precondition that limits must be set in the app, which explains when the tool legitimately returns nothing.

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