sap_set_confirmation_points

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

Annotations only say readOnlyHint=true and destructiveHint=false; the description adds enormous behavioral context beyond that: removal of a point itself asks for approval, declined removal keeps the point, prompts block until answered, fail-closed behavior on clients without elicitation support, and the session-long block when a point cannot be removed. It also explains the double-prompt under all_writes. This is exemplary disclosure of behavior the annotations do not cover.

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?

The description is well-organized with a front-loaded summary line and clear paragraph breaks, but it runs roughly 450 words. The F11 double-prompt illustration and the dense fail-closed/client-without-elicitation passage are informative yet could be tightened without losing meaning. Long, but every section earns its place given the tool's behavioral complexity — it just isn't a model of economy.

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 complex configuration tool, the description covers the essential ground: what each point does, the always-on save gate, server-flag interactions, fail-closed semantics, and a usage hint (call sap_preview first). The only thing left unexplained is the return value, but an output schema exists to cover that. Complete enough for an agent to use it correctly.

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% and there is only one parameter (points, an enum array), yet the description fully compensates: it maps every enum value to its affected tools (transactions → sap_execute_transaction; batch_fields → sap_set_batch_fields; field_writes → the six write tools; all_writes → every write-tagged tool) and characterizes their real-world impact. The agent can choose values correctly with zero schema help.

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 opening line states a specific verb+resource: 'Choose which SAP operations need the user's explicit approval first.' It immediately clarifies this is a policy/configuration tool that replaces the session's confirmation-point set, and it distinguishes itself from all 60+ sibling tools (which are execution, navigation, or read tools) by being the only one that manages approval gating. The purpose is unmistakable.

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 gives unusually rich usage context: it enumerates exactly which tools fall under each point category, explains that 'save' is always on and cannot be turned off, warns that all_writes is 'strict and noisy' with the F11 double-prompt example, notes server --confirm points cannot be removed, and explicitly advises calling sap_preview before a gated action. It tells the agent both what to do and what side effects to expect, which is rare and valuable.

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