fixProposals

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read operation. The description adds that it returns proposals (not edits) and that the result is meant to be passed to fixEdits, which is useful behavioral context. However, it doesn't disclose details like whether proposals are ordered, what happens if no proposals exist, or any rate limits. With annotations covering safety, a 3 is appropriate.

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?

Two sentences with useful information: the tool's purpose, an analogy, examples, and the relationship to fixEdits. It's concise and front-loaded with the core purpose. The only minor issue is that the analogy and examples could be trimmed, but they add clarity for an agent unfamiliar with ADT.

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 read-only proposal tool with annotations covering safety, the description is mostly complete. It explains what the tool returns and how the output is used. However, with no output schema and 0% parameter coverage, the agent lacks details about the exact structure of the returned proposals and the precise meaning of each parameter. The description could also mention what happens when no proposals are available.

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%, so the description must compensate for the four parameters (url, source, line, column). The description mentions 'a position in a source' which maps to line/column and source, but it doesn't explicitly explain each parameter's meaning or format. It doesn't clarify what 'url' refers to (likely the ADT resource URL) or the exact format of source. This is a gap given zero schema coverage.

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 clearly states the tool returns quick-fix proposals for a position in a source, and even gives examples (create missing method, add missing variable) plus an ADT analogy. It distinguishes itself from fixEdits by noting the output is passed to fixEdits for actual edits, which helps differentiate from the sibling 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?

The description implies when to use it: when you need quick-fix proposals for a source position, and it explicitly mentions the output is passed to fixEdits, which is a sibling. It doesn't explicitly state when not to use it or list alternatives, but the ADT light bulb analogy and the fixEdits handoff provide clear context.

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