check_conventions

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

Annotations already declare read-only, idempotent, closed-world behavior, so the bar is lower. The description adds genuinely useful context beyond them: 'Fast and needs no Node.js' (a performance/dependency trait) and 'Each finding cites the style guide section' (output behavior). It doesn't cover error handling when neither input mode is supplied.

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?

Purpose and the key operating constraint are front-loaded in the first two sentences, followed by a compact Args block that earns its space. Minor redundancy between the prose 'Pass either source ... or object_name' and the Args list, but no wasted sentences.

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?

With an output schema present, return-value detail is not required, and annotations cover the safety profile, so the remaining burden is small. The one notable gap is that all four parameters are optional, and the description never says what happens if neither source nor object_name is provided or if both are.

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%, so the description must carry the full burden, and it does document all four parameters inline with meaning: source as ABAP text, object_name as a workspace object 'instead', path as a project folder relative to the workspace root, and max_method_statements as a per-method statement limit. It omits the default of 40 and the default path '.', but the semantics are otherwise self-sufficient.

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: 'Review ABAP against Clean ABAP conventions,' which an agent can act on immediately. It does not, however, differentiate itself from the sibling tool 'lint', which an agent could plausibly confuse it with for static analysis of ABAP code.

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?

Gives clear usage context by explaining the two entry modes: 'source' for a snippet you just wrote versus 'object_name' for an object in the workspace. It offers no explicit exclusions or guidance on when to prefer this over 'lint', so it stops short of full routing guidance.

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