create_radius_profile

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

With no annotations provided, the description carries the behavioral disclosure burden. It warns that a 405 response means RADIUS profile creation is unsupported and profiles are read-only, which is a meaningful behavioral caveat beyond the basic 'create' action. It does not mention permissions or idempotency, but the provided failure-mode note is valuable.

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 efficiently structured: a clear opening line, a line-separated parameter list, and a brief fallback note. Every sentence adds usable information without redundancy or padding.

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 that an output schema exists and the parameter semantics are thoroughly covered, the description is complete for invocation. It clarifies required vs optional fields, host addressing, and includes a fallback instruction for an important edge case, making it self-sufficient for correct tool usage.

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 fully compensates by explaining all nine parameters: host format (console name, ID, or MAC:numericId), site as name/ID, required auth server fields, and optional accounting fields. It adds semantics not present in the schema, such as host allowed formats, port example (1812), and the shared secret purpose.

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?

Description opens with 'Create a RADIUS authentication profile', clearly stating the verb and resource. It differentiates from sibling tools like list_radius_profiles and get_radius_profile by emphasizing creation, and the parameter list reinforces the action.

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 usage context is implied by the creation verb and parameter requirements, but the description goes further by stating that on HTTP 405 the tool should not be used and list_radius_profiles should be used instead. This explicitly gives an alternative and a specific when-not-to-use condition, though it does not broadly cover all sibling alternatives.

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