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

Annotations are empty, so the description carries the full burden. It usefully discloses that no LLM analysis happens, that the result is logged to a quality database, and the relative cost. It omits meaningful write semantics: whether repeat reports for the same service_id overwrite or accumulate, permission requirements, and what confirmation is returned.

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?

Three short sentences, each doing distinct work: what it does, what it does not do, and when to prefer it. The key differentiator is front-loaded after the purpose statement, 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?

For a 4-parameter, 2-required write tool with no output schema, the description covers purpose, cost profile, and routing adequately. The remaining gap is post-call behavior — whether the report is idempotent and what the tool returns — which an agent would want before calling it repeatedly.

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%, including an example format for service_id and units/bounds for response_time_ms, so the schema does the heavy lifting and baseline 3 applies. The description adds no syntax, format, or validation nuance beyond it (e.g., nothing about when notes or response_time_ms are worth supplying).

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 ("Record a simple pass/fail outcome report for a service call") and immediately distinguishes the scope from the sibling verify_outcome. An agent can tell what this does and what it does not do without opening the schema.

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?

Explicitly names the alternative (verify_outcome) and the selection condition: use this when you only need to record success/failure and don't want LLM analysis. It also frames the trade-off (cheaper), which is the practical deciding factor between the two.

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