engineering.db_convert

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

Read-only, idempotent, closed-world safety is already carried by annotations, yet the description still adds real behavioral context: log inputs must be greater than zero, values are Decimal strings with 30 significant digits, and reference is only meaningful in v_to_db and p_to_db. The domain/misuse caveat is genuinely beyond anything the annotations or schema convey. It stops short of describing output shape or error behavior, which keeps it at a 4.

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?

Four dense sentences, front-loaded with purpose then the mode catalog then constraints then the pitfall warning. No filler, no repetition of the title or schema, and the misuse note earns its place by preventing a plausible wrong call.

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?

An output schema exists, so return values need no explanation, and all three parameters plus the domain constraints and precision limits are covered. Nothing an agent needs in order to invoke this correctly 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 coverage is 0% and mode has no enum, so the description carries the full burden — and it does: it lists every valid mode value with its formula, specifies that value is a Decimal string, and states reference defaults to 1 and is used only by v_to_db and p_to_db. This is exactly the meaning the bare schema omits.

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 and resource: converts between dB, Np, dBm and linear values, then enumerates the exact mode set with the formula each applies. An agent can distinguish this from units.convert or engineering.si_prefix_convert without opening the schema, because the log-ratio domain and the mode list are unique to this tool.

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?

It tells the agent which mode to pick implicitly through the formula list (v_to_db vs p_to_db, np_to_db, w_to_dbm) and adds an explicit misuse warning that using p_to_db on a voltage ratio halves the result. What is missing is any statement of when to reach for this tool versus the general-purpose siblings units.convert or engineering.si_prefix_convert.

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