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

Annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) establish that this is a mutation. The description adds context beyond that: creation defaults to a private draft, publish:true releases v1 and makes it public, and there is a license-reuse restriction. No contradiction with annotations.

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?

Four sentences, each earning its place: purpose/scope, default behavior, explicit usage gate, and content preference. The most decision-relevant facts are front-loaded in the first two sentences with zero redundancy.

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?

Given an 11-parameter tool with an output schema and annotations, the description covers the key decisions: draft vs published, license gating, and content preference. It could additionally contrast publish vs release timing or route follow-up edits to update, but nothing essential for a first call 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 the schema already documents all 11 parameters including the publish parameter's meaning. The description adds modest value with "Prefer markdown content in content," reinforcing the schema's own "Prefer content for new writes" note, but does not materially expand parameter understanding beyond the baseline.

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?

"Create an Oi Guardrail in the current organization" names a specific verb, resource, and scope. The default-private-draft behavior and the publish flag implicitly separate this from sibling publish/release tools, so an agent can tell what this tool does 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?

"Use this only when the user explicitly asks to create or import a Guardrail and the source license permits reuse" is an explicit when/when-not gate with a licensing condition. It does not name a specific alternative tool (e.g., update for edits), which keeps it from a 5.

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