suggest_imports

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

With no annotations at all, the description carries the full burden and does so: it discloses the search scope (project sources, JDK, libraries), the exclusion rule (default-package and non-exported packages are never candidates), the ranking algorithm (relevance, then fully qualified name), and the truncation contract (totalCandidates/meta.totalCount count all candidates while meta.truncated flags omissions). That is unusually rich behavioral disclosure for a read-only query tool.

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?

Front-loaded with purpose, then USAGE, then OUTPUT, then the detailed rules — a well-ordered structure. The middle paragraph is dense and slightly run-on around the package-export clause, but every sentence carries information an agent needs to interpret candidate eligibility and ordering.

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?

There is no output schema, yet the description still specifies the return shape (matching types with fully qualified names and relevance) plus the count/truncation metadata, and it names the load_project prerequisite. For a two-parameter query tool, nothing an agent needs to call it 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 100%, so typeName and maxResults are already documented, establishing a baseline of 3. The description goes beyond that by explaining what maxResults actually cuts ('then the first maxResults are returned') and how it relates to totalCandidates and meta.truncated, which is genuine semantic value not present in the schema.

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 ('Find import candidates for unresolved type') and immediately scopes it to the missing-import problem, which cleanly separates it from siblings like organize_imports (which applies imports) and search_symbols (which searches by name without import viability filtering). An agent can route to it 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?

The USAGE line gives a concrete invocation example and 'Requires load_project to be called first' supplies a hard prerequisite that would otherwise cause a failed call. It stops short of explicitly naming organize_imports or stating when-not-to-use it, so 5 is not warranted.

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