Sunaiva Gate — Agent Rule Enforcement

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

With no annotations, the description carries the behavioral transparency burden. It discloses that this is a create operation (implying a write/mutation) and that an API key is required. However, it omits other behavioral traits such as side effects, return value, or error handling, leaving the agent to infer those from the schema or elsewhere.

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 concise sentences clearly convey the purpose and a key prerequisite. No filler or redundant information, front-loaded with the action.

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?

The description covers the core purpose and auth requirement, and the schema fully documents parameters. However, with no output schema and no annotations, the description does not explain return values or any potential side effects/error conditions, leaving some context gaps for a mutation tool.

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?

The schema provides 100% coverage for all 5 parameters, each with descriptions. The tool description adds no parameter-level meaning beyond what the schema already documents, so the baseline of 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 starts with a specific verb ('Create') and a clear resource ('custom detection rule'), with the scope ('in the backend') adding context. This clearly distinguishes it from sibling tools like update_custom_rule, delete_custom_rule, and list_custom_rules.

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 provides clear context for when to use the tool (to create a detection rule) and a key prerequisite ('Requires API key (Pro+)'). It does not explicitly mention alternatives or when-not-to-use, but the purpose verb makes the applicability obvious, and the auth note is a useful guideline.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the authentication requirement and the fact that applying a preset activates rules, but it does not disclose whether applying a preset overwrites existing rules, whether the action is reversible, or any side effects on the current configuration. This is a significant gap for a mutation tool.

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 extremely concise: two sentences that immediately state the purpose and a key requirement. There is no filler or repetition. Every word earns its place, making this an exemplar of concise writing.

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 the tool has only one parameter, no output schema, and no annotations, the description is mostly complete for its simplicity. It covers the core action and a prerequisite. However, it lacks context about the impact on existing rules (e.g., whether it replaces all rules or merges), which is important for safe usage. This incomplete side-effect disclosure prevents a higher score.

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% (preset_id is described as 'ID of the preset to apply'). The description itself adds no additional parameter semantics beyond what the schema already provides. Since the schema covers the parameter, the baseline of 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 clearly states the tool's function: 'Apply a preset bundle, activating all its included rules.' It uses a specific verb ('apply'), a specific resource ('preset bundle'), and explains the effect ('activating all its included rules'). This distinguishes it from sibling tools like list_presets (which only lists) and add_custom_rule (which adds a single rule).

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 provides a prerequisite ('Requires API key (Pro+)') but does not explicitly state when to use this tool versus alternatives like set_rule_mode or update_rules. The context implies usage when you want to apply a preset bundle, but no exclusions or alternative tool references are provided. This is adequate but not exemplary.

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

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

No annotations are present, so the description carries the full burden. It clearly discloses the key behavioral trait: the tool is a stub and returns NOT_IMPLEMENTED. This is more transparent than many descriptions that omit such critical caveats.

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, well-structured sentence that conveys the planned status, the intended functionality, and the current behavior (NOT_IMPLEMENTED). Every element earns its place with no wasted words.

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 this is a planned tool with no parameters and no output schema, the description is sufficiently complete: it states what the tool will do and that it currently returns NOT_IMPLEMENTED. It does not explain the expected return format for future implementation, but that is not necessary for current use.

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?

The tool has zero parameters, so the description does not need to add parameter-level detail. The baseline of 4 applies because there are no parameters to document and no ambiguity exists.

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 clearly states the tool's intended purpose (forward-linked hash-chain / ed25519 audit-log verification) and explicitly notes that it is not yet implemented. This distinguishes it from siblings like get_audit_log, which is for reading logs. The verb is implied ('verify') rather than explicitly stated, but the meaning is unambiguous.

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 tells the agent the tool is not implemented and returns NOT_IMPLEMENTED, which implies it should not be called. However, it offers no guidance on when it would be used in the future or any alternative tools to use instead. Sibling tools like get_audit_log exist but are not mentioned.

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

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

There are no annotations provided, so the description carries the full burden. It discloses the auth/plan requirement, which is useful. However, it does not mention that deletion is permanent or irreversible, nor any side effects, which would be valuable for a destructive operation.

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, front-loaded with the core action, and contains no redundant or extraneous information. It earns its place efficiently.

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 the low complexity (one required param, no output schema), the description covers the essential context: what it does and the auth requirement. It lacks details on return values or consequences of deletion, but this is acceptable for a simple delete tool.

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?

The schema description covers 100% of the parameter ('Rule ID to delete'), so the baseline is 3. The description adds no additional meaning beyond what the schema already provides, making it neither exceptional nor deficient.

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 clearly states the action ('Delete') and the resource ('custom rule'), directly distinguishing it from sibling tools like add_custom_rule, update_custom_rule, and list_custom_rules. It is specific and unambiguous.

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 provides clear context by stating the prerequisite ('Requires API key (Pro+)'), which helps the agent know when the tool can be used. However, it does not explicitly mention when not to use it or suggest alternatives, so it falls short of a full 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that the tool returns recent gate decisions, omitting key behaviors such as the ignored rule_id parameter, default limit behavior, or the shape of the returned data. The schema mentions the rule_id quirk, but the description itself adds no deeper 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?

The description is a single, concentrated sentence with no redundancy. Every word contributes to the core purpose, making it highly efficient for an agent to parse quickly.

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?

The tool is simple (2 optional params, no output schema), and the schema covers parameter semantics. However, the description lacks details about the return format, ordering, or pagination behavior beyond the limit default. Given the absence of annotations and output schema, the description could be more complete, but it is minimally viable for a read-only log tool.

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 both parameters are fully documented. The description adds no extra parameter information, but the schema already explains the limit default and the misleading rule_id behavior. This aligns with the baseline 3 when the schema does the heavy lifting.

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 uses a specific verb ('View') and resource ('recent gate decisions') and enumerates the decision types (blocks, warnings, passes, bypasses). This clearly distinguishes it from sibling tools like log_bypass (which logs bypasses) and audit_verify (which likely verifies).

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 provides no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. It merely states what the tool does without contextualizing its use among the many sibling tools.

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

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

With no annotations, the description must disclose behavioral traits. It mentions the account requirement (Dev+), which is useful, but it does not explicitly state that this is a read-only operation or describe any side effects, error handling, or return behavior. The verb 'List' implies non-destructive behavior, but the safety profile is not fully disclosed.

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, tightly worded sentence that immediately states the tool's purpose and requirement. There is no redundant information or filler; every word adds value.

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 the tool's simplicity (no params, no output schema), the description sufficiently covers what the tool does, for whom, and the access requirement. It does not describe the expected return format, but for a simple listing operation this is not a critical gap. The context is complete enough for an agent to select and invoke the tool 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?

The tool has zero parameters, and the schema coverage is 100% (empty schema). Per the baseline for 0 params, the description need not explain parameters, and it adds no ambiguity. This is adequate.

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 uses the specific verb 'List' with a clear resource ('enforcement-mode overrides') and context ('for the authenticated customer'), which clearly differentiates it from sibling tools like get_rules or list_custom_rules. It precisely indicates the tool's scope and function.

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 provides a clear context (listing overrides) and a prerequisite ('Requires an account (Dev+)'), but it does not explicitly state when to use this tool versus alternatives like set_rule_mode or reset_rule_mode. The usage is implied rather than explicitly guided.

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

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

With no annotations provided, the description carries the full burden and does well by disclosing a critical behavioral quirk: '`category`/`preset` filter args are accepted but not applied server-side.' It also transparently explains the tier-dependent rule composition, giving the agent important context about what results to expect.

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, information-dense sentence. Every clause contributes value, from the tier-specific composition to the filter caveat. It is not overly verbose, though splitting the filter note into a separate sentence could improve readability slightly.

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?

No output schema exists, but the description adequately covers the tool's core purpose, the varying rule sets by tier, and the filter caveat. It does not specify the exact return format, but for a list-type tool this is a minor omission. The description is sufficiently complete for an agent to select and invoke the tool 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?

The input schema already provides descriptions for both parameters ('Filter by preset name' and 'Filter by category'), so the baseline is 3. The description adds significant meaning by explicitly stating that these filter arguments are not applied server-side, which modifies their semantics and prevents misuse beyond what the schema alone communicates.

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 clearly states the tool's purpose: 'List active validation rules.' It further specifies the exact composition of the rule set (constitutional + recommended-default metadata on dev tier, all 69 premium rules on pro+), which differentiates it from sibling tools like list_custom_rules or list_presets. The phrase 'TRUE enforced set' reinforces that this is the authoritative source for active rules.

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 provides clear context for what the tool returns but does not explicitly state when to use it over alternatives or mention exclusions. It implies that this is the complete enforced rule set, which hints at usage scenarios, but no direct comparison with sibling tools is given.

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

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

With no annotations, the description carries the full burden. It discloses the authentication requirement (API key Pro+), but does not describe return format, pagination, or read-only behavior explicitly. The word 'List' implies read-only, but no additional behavioral traits are provided.

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 two short sentences, each earning its place. The first states purpose, the second adds a prerequisite. No redundancy or irrelevant detail.

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 the tool's low complexity (no params, no output schema), the description is mostly adequate: it defines what the tool does and a key access requirement. However, it stops short of mentioning the return type (e.g., an array of custom rules) or error behavior, which would make it fully complete.

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?

The tool has zero parameters, and the input schema is empty, so there is nothing to explain. The description adds no parameter details, but none are needed; baseline for zero parameters is 4.

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 verb ('List'), a specific resource ('custom rules'), and a clear scope ('for the authenticated customer'). It distinguishes from sibling tools like list_presets and get_rules by focusing on custom rules.

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 mentions an API key requirement (Pro+) but provides no guidance on when to choose this tool over alternatives such as get_rules or list_presets. It lacks explicit when-to-use and when-not-to-use instructions.

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

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

The description includes an authentication requirement ('Requires API key (Dev+)'), which is a useful behavioral disclosure. However, it does not explicitly state side-effect safety or return format, though 'List' implies a read-only operation. With no annotations, it partially carries the transparency burden.

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, concise sentence that front-loads the purpose and adds the auth requirement efficiently. Every word earns its place with no waste.

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 parameterless list tool, the description covers the essential aspects: what it lists and the auth prerequisite. It does not describe output format or additional context, but this is acceptable given the tool's simplicity.

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?

The tool has zero parameters, so the input schema is fully covered. The description does not need to explain parameters, and the baseline for zero-parameter tools is 4.

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 uses a specific verb ('List') and a clear resource ('rule preset bundles'), which precisely states what the tool does. It also distinguishes itself from sibling tools like apply_preset and list_custom_rules by focusing on preset bundles.

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 only mentions a prerequisite (API key) but does not indicate when to use this tool versus alternatives such as list_custom_rules or get_rules. There is no explicit guidance on preferred scenarios or exclusions.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. It clarifies that the tool records a bypass rather than performing it, and it states a key constraint (cannot bypass constitutional rules). However, it does not mention side effects, reversibility, or what the outcome of the call is (e.g., success indicator, audit entry).

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 consists of two short, front-loaded sentences: the first states the main action, the second provides a critical constraint. Every word contributes to the value, with no redundancy or filler.

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 simple tool with two required parameters and no output schema, the description provides the essential intent and a significant usage restriction. It could be more complete by stating the outcome of the call (e.g., what is logged, return value), but it is largely sufficient for an agent to select and invoke the tool 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?

The schema already provides 100% coverage for both parameters with clear descriptions ('Justification for the bypass' for reason, 'ID of the rule to bypass' for rule_id). The description's phrase 'with justification' reinforces the reason parameter but does not add substantive new meaning beyond the schema.

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 uses a specific verb ('Record') and resource ('intentional rule bypass') with a clear qualifier ('with justification'), making the tool's purpose unambiguous. It inherently distinguishes itself from siblings that add, delete, or update rules by focusing on logging a bypass event.

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 explicitly states when to use the tool ('Record an intentional rule bypass') and provides a clear exclusion ('Cannot bypass constitutional rules'). This gives the agent direct guidance on when the tool is appropriate and when it is not.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does state that an API key (Pro+) is required and that the action reverts a rule to its default, but it does not specify whether the operation is idempotent, what happens if the rule has no override, or any error behavior. This adds some value but leaves gaps.

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, front-loaded sentence that covers the action, result, and a prerequisite. Every word earns its place, with no fluff or 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?

For a simple tool with one parameter and no output schema, the description covers the core purpose, required auth level, and the resulting behavior. It does not explain edge cases (e.g., no override exists) or return values, but these are minor for a low-complexity tool.

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?

The input schema has 100% coverage: the only parameter (rule_id) is described as 'Rule ID whose override to remove'. The tool description adds no additional parameter-specific detail, so with high schema coverage, the baseline of 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 uses a specific verb ('Remove') and a resource ('mode override for a rule'), clearly stating the outcome ('reverting it to its default enforcement mode'). This distinguishes it from siblings like set_rule_mode, which sets an override, and get_rule_modes, which retrieves them.

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 clearly implies its use case: when you need to remove an existing mode override and return to the default. The 'Requires API key (Pro+)' line adds a prerequisite, though it does not explicitly contrast with set_rule_mode or mention when not to use it. This is clear context but lacks explicit exclusions.

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

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

With no annotations present, the description carries the full burden of behavioral disclosure. It only mentions the API key requirement; it does not state whether the action is reversible, what side effects occur, or what the response looks like. For a mutation tool, this is a significant gap.

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 extremely concise—two short sentences that immediately convey the core operation and the key prerequisite. There is no unnecessary wording, and the essential information is front-loaded.

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?

The tool is relatively simple but would benefit from additional context. There is no output schema, yet the description does not mention return values or confirm the effect of the change. It also does not explain how this differs from reset_rule_mode. Overall, it is adequate but leaves important gaps for a state-changing tool.

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?

The schema already provides 100% coverage of all three parameters, including clear descriptions and an enum for mode. The description adds no additional parameter-level meaning, such as what each mode does or the purpose of agent_id, so it neither compensates nor detracts from the schema.

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 clearly states the action ('Set') and the resource ('enforcement mode for a specific rule'), and enumerates the allowed modes (shadow/advisory/enforce). However, it does not explicitly differentiate itself from sibling tools like reset_rule_mode, so it lacks explicit sibling differentiation.

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 gives no guidance on when to use this tool versus alternatives such as reset_rule_mode or get_rule_modes. The only additional note is the API key requirement, which is a prerequisite, not a use-case discriminator.

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

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

With no annotations, the description carries the full burden. It clearly discloses that the tool is planned, not yet implemented, and specifically returns NOT_IMPLEMENTED. This is a precise and honest behavioral disclosure. However, it does not describe the intended behavior when/if implemented, which limits richness but does not contradict anything.

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, concise sentence that immediately states the critical fact (not implemented, returns NOT_IMPLEMENTED). It wastes no words and front-loads the most important information.

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 this is a stub tool with no output schema and simple parameters, the description is sufficient to inform an agent that the tool is unavailable. It clearly indicates the NOT_IMPLEMENTED response. The only missing element is guidance on what the intended check would do, but for a planned stub this is adequate.

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 baseline is 3. The description adds no parameter-specific information beyond what the schema already provides. It mentions 'dual-tier authorization' but does not map that concept to the provided parameters (e.g., artifact_id, command_preview).

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 lacks a verb phrase; it states 'Ship Confidence Gate (Rule 42) dual-tier authorization is not yet built' but never says what the tool would do (e.g., 'checks' or 'authorizes'). It conveys that the feature is planned and unimplemented, so the actual purpose is implied by the name and context, not explicitly stated.

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 guidance on when to use this tool. The description notes it is not implemented and returns NOT_IMPLEMENTED, which implicitly discourages use, but it does not suggest alternatives among siblings like 'validate_action' or 'audit_verify'. No clear use case or exclusion criteria are provided.

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

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

No annotations are available, so the description must disclose behavioral traits. It mentions the API key requirement, which is useful, but fails to indicate whether updates are partial or full, what fields are affected, or any side effects. The schema contains a critical note about 'detection_pattern' being the only accepted field name, but the description omits this important behavioral detail.

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 very concise: two short sentences that immediately state the operation and a requirement. No filler words.

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 the tool's complexity (6 parameters, no annotations, no output schema), the sparse description is insufficient. It lacks information about update semantics, param details, and the documented field-name constraint, making it inadequate for an agent to fully infer correct 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?

The description does not explain any of the six parameters. Schema coverage for descriptions is only 33%, and the description adds no param-level detail, leaving most parameters (name, tier, severity, description) undefined from the text.

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 clearly states the verb 'update' and the resource 'existing custom rule', making it a specific modification operation. However, it does not differentiate from the sibling tool 'update_rules', leaving some ambiguity about individual vs bulk updates.

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?

No guidance is provided about when to use this tool instead of add_custom_rule, update_rules, or other alternatives. The only additional note is the API key requirement, which is a prerequisite, not a usage recommendation.

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

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

With no annotations provided, the description fully discloses the behavioral trait that the tool returns NOT_IMPLEMENTED and is not backed by a route. This is complete transparency beyond the schema.

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?

A single, information-dense sentence that front-loads the critical warning and provides a clear alternative. No redundant words; each segment earns its place.

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 tool that is not implemented, this description is fully complete: it states the planned behavior, the actual return value, and the correct alternative. No additional context is needed.

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% and already explains 'enable' and 'disable' as arrays of rule IDs. The description adds no new parameter-level meaning, so the baseline of 3 applies.

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?

Clearly states the intended function (enable/disable rules) and explicitly notes it is not implemented, distinguishing it from the alternative set_rule_mode. The tool name and description align on the resource, and the scope is made unambiguous.

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 instructs the agent not to use this tool and points to the preferred alternative (set_rule_mode) or a local package, providing definitive when-to-use and when-not-to-use guidance.

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

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

With no annotations, the description carries the burden. It discloses the output format (allowed/blocked with violations) and the scope (active rules), but does not state whether the operation has side effects or is read-only. Given it's a validation tool, this is a moderate gap.

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 two short sentences with no fluff, immediately conveying the core function and return. It is efficiently structured.

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?

The description covers the primary purpose and return shape without an output schema. It doesn't mention edge cases or whether it modifies state, but for a simple validation tool it is reasonably complete. Some additional context about validation workflow could help.

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?

The schema already provides 100% parameter coverage, including a helpful explanation of how context appends to action. The description adds no additional parameter details, which is acceptable given the schema's clarity.

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 clearly states the tool checks a proposed action against all active validation rules and returns allowed/blocked with violations. It is distinct from sibling tools that manage rules, but does not explicitly name 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 this tool should be used to validate actions before execution, but provides no explicit guidance on when to use it vs alternatives like ship_confidence_check or log_bypass, nor mentions any exclusions.

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