create_ssl_ssh_profile

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

No annotations are provided, so the description carries the full burden. It confirms this is a mutation that returns a status/name/message dict, but says nothing about side effects, permission or ADOM-lock requirements, idempotency on duplicate names, or validation failure behavior. The Returns block duplicates the existing output schema rather than adding behavioral context.

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?

Front-loaded one-line purpose followed by a scannable Args block, an example, and a Returns section; given 0% schema coverage the parameter enumeration is justified. The Returns section is somewhat redundant with the existing output schema and the example's necessary value is modest, but there is no filler prose.

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 an 11-parameter mutation with no annotations, the parameter surface is well covered, but key operational context is missing: prerequisites (ADOM scope, existing CA certificate objects), name-collision behavior, and any caveat about SSL deep-inspection implications. Since an output schema exists, the Returns block need not have been repeated.

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% across 11 parameters, and the description compensates almost fully: it names the allowed values for ssl_inspection/https_inspection ('disable', 'certificate-inspection', 'deep-inspection'), server_cert_mode ('re-sign'/'replace'), notes that caname/untrusted_caname/server_cert are datasource names, and states the conditional dependency that server_cert is only used when server_cert_mode='replace'. Minor gaps remain (mapi_over_https/rpc_over_https are only described as 'Enable/disable' without stating accepted literal values).

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+resource ('Create an SSL/SSH inspection profile') that is unambiguous against siblings like update_ssl_ssh_profile, get_ssl_ssh_profile, and list_ssl_ssh_profiles. It does not explicitly name a sibling or a disambiguation condition, so it stops short of a 5.

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?

There is no explicit when-to-use guidance, no prerequisites (e.g., ADOM must be unlocked/editable, referenced CA certificate datasources must already exist), and no mention of what to do if a profile with that name already exists (vs. update_ssl_ssh_profile). Usage is only implied by the verb 'Create'.

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