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

With no annotations provided, the description carries the full transparency burden. It only states 'Check the status' without disclosing whether this is a read-only operation, any permission requirements, rate limits, or what side effects (if any) exist. This leaves behavioral traits largely undisclosed.

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: 'Check the status of a specific API action by ID.' It is concise and every word contributes to the meaning, though it is minimal.

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 there is no output schema and no annotations, the description should explain what the tool returns or any additional context, but it simply describes the action without specifying the response format or any caveats. This leaves the tool insufficiently documented for an agent to know what to expect.

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 documents action_id with 'The action UUID to check,' and the description merely echoes 'by ID.' Since schema coverage is 100%, the description adds no additional semantic value 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 clearly states the tool's function: 'Check the status of a specific API action by ID.' It presents a specific verb and resource, but does not explicitly differentiate from sibling tools like compliance_status or evaluate_action, so it's clear but lacks sibling distinction.

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 when to use it (when you have an action ID and need its status), but provides no explicit guidance on alternatives or scenarios when not to use it. It does not mention sibling tools 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?

No annotations exist, so the description carries the burden. It discloses a key behavioral trait: write actions are queued for dashboard approval. This goes beyond the schema and provides useful safety context, though it leaves some behavior (e.g., response format) unspecified.

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?

Three short sentences, front-loaded, no fluff. Each sentence adds value: purpose, capabilities, and write-approval queuing.

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 and no annotations, so the description should cover return values and usage boundaries. It explains capabilities and write approval but does not describe what the agent can expect in the response or when to use specific sibling tools, leaving some gaps.

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% with examples for both parameters. The description adds minimal new meaning beyond 'natural language message' and does not elaborate on conversation handling, so baseline 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 sends natural language messages to GuardEntry and enumerates capabilities (query, create, generate). This distinguishes it from sibling tools like guardentry_list_risks which are structured queries.

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 use for general natural language interaction but does not explicitly state when to prefer this over more specific sibling tools or exclude structured actions. It provides context but no explicit when/when-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?

No annotations are provided, so the description carries the burden. It discloses the scoping behavior (specific or all frameworks) but does not explicitly state read-only semantics, though the verb 'Get' implies it. It does not mention response format, authentication, or side effects.

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?

Single sentence, front-loaded with the verb, no extraneous information. Perfectly sized for the tool's simplicity.

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 read tool with one optional parameter and no output schema, the description adequately conveys the purpose and scope. It could potentially explain what a 'readiness status' looks like, but given the simplicity and the sibling context, it is largely 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 input schema covers 100% of the parameter's description, listing valid framework codes. The description adds value by clarifying that omitting the framework returns all frameworks, which is not explicit in the schema (only implied by the param being optional).

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 retrieves compliance readiness status, with explicit scope ('specific framework or all frameworks'). It distinguishes from sibling tools by focusing on status retrieval rather than risk listing, policy management, or agent actions.

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 (when compliance status is needed) but does not explicitly state when to prefer this tool over alternatives like guardentry_list_risks or guardentry_get_agent_policy. There are no exclusion criteria or alternative references.

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 primary effect—promoting a policy from inferred to confirmed and making it active—but does not mention reversibility, permissions, or other side effects. This adds value but leaves some gaps, so a 3.

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 concise sentences: the first states the action and effect, the second provides usage context. No redundant or filler content.

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 single-parameter state-transition tool, the description covers purpose and when to use it. It lacks mention of return behavior or error conditions, but these are not essential given the simplicity and absence of an output schema. Overall adequate and mostly 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 schema already covers the only parameter with a clear description ('UUID of the policy to confirm'), and the tool description does not add further parameter-specific semantics. With 100% schema coverage, the baseline is 3.

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 confirms an inferred agent policy and makes it active, with the state transition from 'inferred' to 'confirmed'. This distinguishes it from siblings like 'guardentry_update_policy' or 'guardentry_get_agent_policy', using a specific verb and resource.

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?

It specifies the usage scenario: 'Use after reviewing an auto-generated policy to promote it from inferred to confirmed.' This gives clear context and implies when to use the tool, though it does not explicitly name alternatives or exclusions, so it stops short of a 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?

No annotations are provided, so the description carries the full burden. It reports the return type ('decision with reasoning') and implies non-execution via 'Evaluate' and 'Use before', but it does not explicitly state that the action is not executed or that there are no side effects. It also omits policy fallback/inference behavior, though the schema covers these details.

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 sentences, front-loaded with the main purpose and followed by a direct usage directive. Every word earns its place; 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?

Given the tool's complexity (9 params, nested policy object, enums) and the rich schema descriptions, the description adequately orients the agent to core purpose and timing. It does not enumerate all subject types (missing 'plan' and 'tool_result') or the policy resolution cascade, but those gaps are largely filled by the extensive schema.

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 extra parameter-level meaning; it does not explain how to choose mode, provide inline policy, or select subject_type beyond what the schema already documents.

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 ('Evaluate') and clearly defines the decision output (allowed/blocked/requires approval). It distinguishes the tool from siblings like guardentry_get_agent_policy and guardentry_list_pending by focusing on policy-based action evaluation rather than policy retrieval or pending item listing.

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: 'Use before any agent executes a sensitive task, tool call, or prompt.' This provides clear invocation context. It does not name alternatives or exclusions, but the timing guidance is sufficient for most decision-making.

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?

Without annotations, the description carries full transparency burden. It discloses the important behavior that a default policy is returned when no explicit policy exists, adding value beyond the tool's name. It does not detail error cases, but 'retrieve' implies non-mutating behavior.

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 sentences with no unnecessary words. The primary action is front-loaded, and the additional sentence explains a key edge case, making it both concise and informative.

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 simple nature of the tool and full schema coverage, the description adequately explains the core purpose and behavior. It does not explicitly state that at least one of agent_id or agent_type is needed, but that is implied by the schema descriptions and acceptable for a low-complexity retrieval 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 covers all three parameters with descriptive text, achieving 100% coverage. The description does not add extra meaning beyond the schema, so baseline 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 'Retrieve the effective policy for an agent' with a specific verb and resource, and it explains the behavior when no explicit policy exists. This distinguishes the tool from sibling tools like update_policy and confirm_policy by focusing on retrieval.

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: use this tool to get an agent's effective policy, including inferred defaults. It does not explicitly name alternatives or exclusions, but the purpose is distinct enough to imply appropriate usage.

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 transparency burden. It discloses a key behavioral trait: write actions are queued for dashboard approval, meaning results may not be immediately applied. It also states the agent returns results, which sets expectations. It doesn't cover authentication or rate limits, but the queuing and execution behavior are sufficiently 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 two concise sentences, front-loaded with the primary purpose. Every phrase adds value: invocation method, execution behavior, and write-action queuing. No fluff or repetition.

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 with no output schema and no annotations, the description covers what the tool does, how parameters relate, and a critical side effect (queued writes). It doesn't specify the output format, but 'returns results' is adequate given the schema. It could mention that action_status can track queued operations, but the current level is sufficient for a non-trivial invocation 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 coverage is 100%, and each parameter has a clear description (agent_id as UUID, agent_type as fallback). The description only mirrors 'by ID or type' without adding new parameter-level meaning. The baseline of 3 applies because the schema already documents parameters well.

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 invokes a GuardEntry agent by ID or type, with a specific verb and resource. It distinguishes from sibling tools like invoke_skill (which runs a skill instead of an agent) and list_* tools by focusing on execution. The added detail about configured skills (vulnerability scanning, compliance, risk) reinforces scope.

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 context: 'The agent executes its configured skills' suggests that if you want to run a specific skill, you might use invoke_skill instead. It also notes that write actions are queued for approval, indicating this tool is for triggering agent runs, not for direct mutations. However, no explicit exclusions or alternative tool names are 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals a significant trait: read vs. write skills behave differently, with writes being queued for approval. It does not detail return formats or post-approval behavior, but this is a substantial disclosure for a two-sentence description.

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 sentences long, directly addresses purpose and behavior, and includes examples. Every word earns its place 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?

While the description explains read vs. write behavior, it lacks any mention of the response/return format, which is important given there is no output schema. It also does not reference sibling tools like list_pending or action_status, which could be needed to track queued write skills. This leaves a notable gap for a tool that can trigger asynchronous actions.

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 documents both parameters with 100% coverage. The description adds value by providing example skill_id values and indicating that 'input' varies by skill, which helps the agent understand the dynamic nature of the input parameter.

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: 'Invoke a single GuardEntry skill directly' with concrete examples (compliance_check, risk_analysis, scan_vulnerabilities). This distinguishes it from sibling tools like invoke_agent, which target agents, and list_skills, which only lists skills.

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 on when to use the tool (to invoke a skill directly) and important behavioral distinctions: read skills execute immediately, write skills are queued for approval. It does not explicitly name alternatives or exclusions, but the 'directly' phrasing and examples differentiate it from agent invocation.

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 must carry the burden of disclosing behavior. It indicates a read operation through the verb 'List' and clarifies the filter scope ('pending... awaiting dashboard approval'), but does not explicitly state side effects, permissions, pagination, or return format. This is acceptable for a simple listing tool but lacks depth.

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 verb and resource, with no redundant words. It efficiently conveys the tool's core purpose.

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 (one optional parameter, no output schema, no annotations), and the description provides the essential purpose. However, it does not explain what an 'API action' is, how results are presented, or when to prefer this over the sibling action_status tool, leaving some contextual gaps.

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% (the 'status' parameter has a description with enum values and default). The tool description does not add parameter-level detail beyond the schema, so baseline 3 applies. The schema already explains the filter and default.

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 'List pending API actions awaiting dashboard approval' uses a specific verb (List) and resource (pending API actions), clearly defining its purpose. It distinguishes from sibling tools like guardentry_list_risks (risks vs actions) and guardentry_action_status (status of a specific action vs list of pending).

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 when you need to view pending API actions awaiting approval, but provides no explicit when-to-use or exclusion guidance relative to sibling tools like guardentry_action_status or guardentry_confirm_policy. There are no alternatives mentioned, so the context is only implied.

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 provided, so the description must disclose behavioral traits. It mentions the return content but does not state whether the operation is read-only, requires permissions, or has side effects. This is a significant gap for a tool with no annotation-backed safety hints.

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 that immediately state the action and the return value. It is front-loaded, concise, and contains no fluff.

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 basic purpose and return format, which is helpful given there is no output schema. However, it lacks any mention of safety, permissions, or error behavior; for a simple list tool with one optional filter, it is reasonably complete but not fully.

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 fully documents the 'status' parameter with enum values and a description, so the description adds no new parameter information. With 100% 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 clearly states the tool lists the organization's risk register and specifies the returned data (severity scores, status, descriptions). It does not explicitly distinguish from sibling tools, but the name and description are 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 no guidance on when to use this tool versus alternatives such as guardentry_list_pending or guardentry_list_skills. No context for selection or exclusions 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?

No annotations are provided, so the description carries the full burden. It clearly indicates this is a read-only listing operation ('List all...') and adds that results are grouped by category. However, it does not explicitly disclose that it has no side effects, requires no permissions, or any other behavioral traits, but for a simple list tool this is adequate.

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 front-loads the action ('List all available...') and provides useful additional detail (grouping) without any 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?

For a simple parameterless list tool with no output schema, the description fully explains what the tool does and what the output contains (skills with descriptions, grouped by category). There is no missing information that would prevent an agent from selecting and invoking 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?

The tool has zero parameters, and the schema is an empty object. The description needs to explain no parameters, and the baseline for 0 params is 4. It adds no extra parameter information because none is needed.

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' and identifies the resource ('available GuardEntry agent skills'). It also specifies the output grouping ('by category: research, analysis, write, output'), which clearly distinguishes it from sibling tools like guardentry_list_risks or guardentry_invoke_skill.

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 when to use this tool (when you need to list available skills) but does not explicitly state when not to use it or mention alternatives (e.g., for invoking a skill, use guardentry_invoke_skill). There is no exclusionary guidance, so it falls short of a 4.

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 exist, so the description carries the full burden. It discloses a version snapshot is saved before each update, which adds useful behavioral context, but it omits permissions, replacement semantics, rollback behavior, and failure modes. More detail is needed 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 concise (two sentences) and front-loads the primary verb and resource. The list of categories is useful, but the inaccurate 'allowed tools' wording slightly detracts from precision.

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 with 8 parameters and no annotations or output schema, the description provides a clear purpose and notes version snapshots, but lacks critical context such as whether unspecified fields are unchanged or reset, required permissions, and return values. It is minimally adequate but has clear gaps.

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 every parameter. The description adds a category mapping but includes an imprecise phrase: 'allowed tools' is not a schema property (there is 'blocked_tools' and 'allowed_actions'). Baseline 3 applies because the schema handles 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 clearly states the tool updates an agent policy's rules and enumerates the specific categories (blocked actions, allowed tools, require-approval patterns, risk tolerance, mode). This distinguishes it from sibling read tools like get_agent_policy and confirm_policy.

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 that this tool is for modifying policy rules, and its purpose is obvious given siblings like get_agent_policy/confirm_policy. However, it does not explicitly mention when not to use it or suggest alternative tools for other operations.

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