invariance_guardrail_create

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a write operation that is not destructive. The description adds that a title is required and that creation can come from a recipe or finding, which is useful context. However, it doesn't disclose what happens on creation (e.g., whether it auto-activates, what the default status is, or whether it validates the rule). With annotations covering the safety profile, a 3 is appropriate.

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 a single sentence that front-loads the core purpose and then lists the required and optional fields. It's efficient and scannable. It loses a point because the field list is somewhat redundant with the schema, but it's still compact and useful.

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 create tool with 7 parameters, no output schema, and 0% schema description coverage, the description is adequate but thin. It tells the agent what is required and what options exist, but it doesn't explain the difference between mode and status, whether recipe_id and finding_id are mutually exclusive, or what the response looks like. Given the tool's complexity (7 params, 2 enums), more context would help an agent call 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 description coverage is 0%, so the description must compensate for the 7 parameters. It does list the parameter names (title, recipe_id, finding_id, rule, mode, status) and marks title as required, which adds some meaning. However, it doesn't explain the semantics of mode vs status, the relationship between recipe_id and finding_id, or what 'rule' should contain. The enum values in the schema are self-explanatory, but the description doesn't clarify when to use which optional field. This is a partial compensation for the 0% coverage.

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 clear verb and resource: 'Create a guardrail (from a recipe or finding).' It also lists the required and optional fields, which helps distinguish it from sibling tools like invariance_guardrail_update and invariance_guardrail_promote. However, it doesn't explicitly contrast with those siblings, so it loses a point for not naming alternatives.

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 implies usage by saying 'from a recipe or finding' and lists optional fields, which gives some context for when to use it. But it doesn't explicitly state when to use this tool versus invariance_guardrail_update or invariance_guardrail_promote, nor does it mention any prerequisites or exclusions. The guidance is implied rather than explicit.

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