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

With no annotations, the description carries the full burden and does so thoroughly: in-memory AES-256-GCM encryption, no disk persistence, no echoing, session-scoped caching, expiry behavior, and the disabled locked-server path. This is far beyond a minimal mutation warning and gives the agent accurate behavioral expectations.

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 tight paragraphs with front-loaded purpose, followed by security behavior and the deployment exception. Every sentence adds information; no filler, no restating of schema defaults.

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?

Invocation-critical context is complete: what the tool does, how long the connection lasts, what consumes it, and when it is unavailable. The only minor gap is the lack of any description of the response/error behavior, but since no output schema exists and this is a simple setter, the missing piece is not severely damaging.

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 100%, so the schema already documents every parameter. The description adds useful grouping context ('URL + Entra app-registration credentials') and security emphasis for clientSecret, but it does not need to detail each parameter further. Baseline 3 is appropriate.

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 action ('Securely register the D365 F&O connection') with a clear resource (URL + Entra app-registration credentials) and scope (CURRENT session). It also distinguishes itself from d365fo_clear_connection and implicitly from appinsights_set_connection by naming the D365 F&O context and the odata_*/dmf_* consumers.

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?

Explicitly says when to use it ('Use this instead of resending the secret on every call'), defines the automatic consumption by odata_* and dmf_* tools, and states a clear when-not case with D365FO_LOCK_SERVER_CONFIG=true. This gives an agent concrete conditions for selection.

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