springboot_detect_drift

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower; the description still adds useful semantics: the response is differences plus graded root-cause candidates, and the caveat that file timestamps alone cannot prove a process was not restarted. That caveat is non-obvious interpretation guidance not present in the annotations.

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 sentence, front-loaded with the comparison verb, with semicolon-separated clauses that each carry a distinct fact: what is compared, what is returned, when to call, omission semantics, and the timestamp caveat. 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?

An output schema exists, so return values needn't be described, and the core comparison contract is stated. But for an 11-parameter tool with nested objects, the description leaves the control parameters (target, pagination, scope-completeness, source revision vs. modification time) unexplained, which is a real gap for correct invocation.

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 0% across 11 parameters. The description names only the four expected* dimensions (beans, routes, migration version, profiles) and the omission rule; it says nothing about targetId (the 'authorized workspace'), cursor, maxResults, maxDepth, sourceRevision, sourceModifiedAt, or expectedScopeComplete, which materially change comparison behavior. Most parameters have no semantics anywhere.

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 specific verb (compare) and specific resources (Bean, route, migration version, Profile expectations vs. runtime), and the drift framing separates it from the sibling tools that inspect those things individually (inspect_beans, verify_mappings, check_migrations). An agent can identify this as the cross-dimension comparison tool without comparing schemas.

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 states a clear trigger — call when source code and runtime behavior disagree — and adds the rule that omitted dimensions are not compared, which tells the caller the call is valid with partial input. It does not name a sibling as an alternative or state when not to use it, so it falls short of 5.

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