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

Even with destructiveHint=true already present, the description adds crucial behavioral context by explicitly warning that the upload REPLACES the secret's contents and by instructing confirmation before executing. This goes well beyond annotations and directly addresses the destructive nature.

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 sentences, each earning its place: the core action and replacement behavior, the confirmation requirement, and the alternative tool. The destructive consequence is front-loaded, and there is no filler or repetition of schema details.

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 destructive two-parameter tool with no output schema, this description is complete. It tells the agent what the tool does, what the destructive effect is, what safety step to take, what to tell the user, and when to choose a different tool. Nothing essential for selecting or invoking it correctly is missing.

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 already fully documented with clear type and path expectations. The description adds little parameter-specific meaning beyond what the schema provides, keeping this at the baseline appropriate for high schema 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 uses a specific verb-resource pair: uploads variables from a directory's .env into the linked secret, and explicitly states it replaces what the secret held. It also distinguishes itself by calling out oneguard_env_sync as the reverse, leaving no ambiguity about what the tool does.

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 provides explicit operational guidance: confirm with the user first and tell them which variable names are about to be uploaded. It also names an alternative tool for a distinct use case ('To add a single generated value without touching the rest, use oneguard_secrets_generate instead.') and identifies this as the reverse of oneguard_env_sync.

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 read-only nature is already captured by the readOnlyHint annotation, and the description repeats it. The description adds useful output behavior (reports linked secret and variable names), but it does not mention edge cases, prerequisites, or what happens when a directory is not linked. It adds some context beyond the annotation 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?

A single sentence that front-loads the core capability and includes only necessary detail. No filler or redundancy; the sentence is immediately 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?

For a simple read-only tool with no output schema, the description conveys the kind of information returned. It covers the main scenarios (linked vs. not linked, variable names) but does not mention failure modes or filesystem assumptions. Given the tool's simplicity, the definition is reasonably 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?

Schema description coverage is 100%, so both parameters are already documented with clear descriptions. The tool description adds no additional parameter-level semantics. Baseline 3 is appropriate because the schema carries the load.

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 ('Reports') and clearly identifies the resource (a directory's sync state) and the three facts it returns: whether it is linked, which secret, and which variable names are in the .env. It is distinct from generic 'status' tools even though it does not explicitly name an alternative.

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 given about when to prefer this tool over siblings such as oneguard_status or oneguard_env_sync. The description provides no context, prerequisites, or exclusions, so an agent gets no help choosing between 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?

Beyond the annotations, it discloses important behavioral traits: values go to disk and are never shown, only variable names are returned, and the tool remembers the link. It also reveals the two-phase behavior on first use. This adds substantial context beyond readOnlyHint=false.

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 front-loaded with the core operation and packs workflow, return behavior, and privacy into a compact block. The phrase 'THE MAIN TOOL' is unnecessary, but it does not distract much. Every other sentence contributes 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?

With no output schema, the description correctly explains what is returned ('only the variable NAMES that were written') and the important guarantee that values are never displayed. It also covers both linked and unlinked invocation paths, so an agent can call the tool correctly in either state.

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 baseline is 3. The description adds interaction semantics for vault and secret: they are only needed when the directory is not yet linked, and on the first call the tool returns choices rather than requiring them upfront. This goes beyond the schema's individual parameter descriptions.

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 action: 'Fetches the secret linked to a directory and writes it into that directory's .env file, then remembers the link.' This clearly identifies both the resource and the operation, and the 'writes into .env' framing differentiates it from sibling push/list tools.

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 concrete invocation guidance: call with only project_dir when already linked, and if not linked, return choices, let the user pick, then call again with vault and secret. It does not explicitly name alternative tools or exclusions, but the workflow is explicit and actionable.

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?

Annotations indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds clarity by stating that the .env file is untouchedpis, which is important behavioral context. As an idempotent operation, the description could mention that it is safe to run even if no link file exists, but this is implied.

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 convey the purpose, side effect, and equivalence to a CLI command with no fluff. The description is front-loaded with the primary action and key side effect.

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 only one parameter, idempotent annotation, and no output schema, the description covers the essential behavior. It could mention what happens if the link file doesn't exist, but the idempotentHint covers that implicitly. The external command equivalence adds operational context.

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 describes project_dir thoroughly. The description doesn't add extra parameter syntax, but it reinforces that the directory is where both the link file and .env reside. Since there is only one parameter and it is well documented, the minimal description contribution is acceptable.

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 'Removes' and the resource '.oneguard link file', and specifies what is not affected ('The .env file on disk is left untouched'). It is distinguished from sibling operations like oneguard_env_sync and oneguard_env_push by its focus on the link file removal.

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 the tool is used to unlink a directory from environment synchronization, and explicitly mentions the equivalent CLI command. However, it does not state when to use this tool versus oneguard_env_sync or oneguard_env_status, nor does it mention any prerequisites (like an existing link file) or when not to use it.

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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds meaningful behavioral context beyond that: generation is local, nothing is stored, and the returned value passes through the conversation. This caveat about value exposure is highly relevant for an AI agent deciding whether to call the 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?

Three short sentences with no wasted words. The core action is front-loaded, followed by the important no-storage guarantee and the routing caveat. Every sentence 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 with all-optional parameters, a fully self-documenting schema, and read-only annotations, the description covers purpose, privacy, and the correct alternative. It does not specify the exact return format, but 'returns them' is sufficient given the schema and the simple nature of the 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% with descriptions and defaults for all 8 parameters, so the description does not need to repeat parameter-level details. It adds no extra parameter semantics, which lands at the baseline for fully documented schemas.

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 exactly what the tool does: generates random values locally and returns them. The description also differentiates it from oneguard_secrets_generate by explicitly contrasting the storage/revelation behavior, so an agent can distinguish the two without opening the schema.

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?

Provides an explicit decision rule: if the generated value is going into a OneGuard secret, use oneguard_secrets_generate instead. It names the alternative and the condition that selects it, which is clear routing 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?

Annotations already declare idempotentHint=true and destructiveHint=false. The description adds valuable context: the key is stored in an isolated config directory, does not affect the user's own terminal login, and the tool verifies against the backend. It doesn't fully describe failure modes or what happens on repeated calls, but the idempotent annotation covers that.

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 well-structured: states the action, explains when it's unnecessary, gives the exact condition for calling, and adds a security warning. Every sentence earns its place with no 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 single-parameter initialization tool with idempotent and non-destructive annotations, the description covers the essential context: when to call, what it does, side effects on storage, and the security constraint. No output schema exists, but the description's verification mention implies what the agent needs to know.

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 the parameter is simple. The description adds the crucial semantic that omitting the key uses the server-configured ONEGUARD_API_KEY, which goes beyond the schema's 'Omit to use the ONEGUARD_API_KEY configured on the server' — actually the schema already says this. The description reinforces the security constraint about not inventing keys. Baseline 3 for full coverage, but the description adds meaningful context about the key's origin and storage.

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 initializes the server's isolated OneGuard session with an API key and verifies it against the backend. It distinguishes itself from siblings by being the only initialization tool among the listed operations.

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 says when NOT to call it (normally not needed, auto-initializes), when to call it (only when another tool reports the server is not initialized), and provides a critical constraint (only use a key the user gave in this conversation, never invent one). This is exemplary usage 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?

The readOnlyHint annotation already covers the safety profile, and the description adds content semantics but no additional behavioral traits such as ordering, pagination, or time-range behavior. Since annotations carry most of the burden, a mid score 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?

A single, front-loaded sentence states the resource, the content, and a practical use case. No filler or repetition; every element 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 one-parameter read-only tool with annotations covering safety, the description and schema together are sufficient. It covers what the log contains and a motivating use case; minor gaps such as explicit ordering or time-range details are not critical for correct invocation.

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 parameters, including a clear description of 'limit' as returning 'most recent entries.' The description adds no parameter-specific detail beyond the schema, so baseline 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?

Description uses a specific verb and resource: 'Returns the organization audit log' and details the content as 'who did what to which resource, and when.' This clearly distinguishes it from sibling list tools like oneguard_vault_list or oneguard_secrets_list, which target different resources.

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?

Gives a concrete usage context: 'Useful for answering "who changed this secret" questions.' This implies when to reach for this tool, though it does not explicitly name alternatives or state when not to use it.

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 annotations already establish this is a mutating but non-destructive operation. The description adds valuable behavioral context: passing a value directly exposes it in the conversation, generated values are never revealed by the sibling tool, and secret values must come only from the user or their .env file. It does not disclose what happens on conflict (e.g., overwrite), but this is a minor omission given the annotations.

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?

Four focused sentences with no filler. The purpose is front-loaded, followed by practical usage preferences and a hard constraint. Every sentence contributes actionable guidance.

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 6-parameter create tool with no output schema, the description covers the essential usage decisions well: main purpose, preferred input mode, security implications, and linkage to the generation workflow. It does not describe the return value or confirmation behavior after creation, which is a minor gap for a tool that produces a new resource.

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 baseline is 3. The description adds meaning beyond the schema by explaining the tradeoff between from_env_file and direct key/value pairs, emphasizing that direct values 'travel through this conversation,' and implicitly connecting project_dir to where the .env file lives. This guidance helps the agent choose parameters correctly.

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 action ('Creates a new secret in a vault') with a clear resource and method, and distinguishes itself by the two accepted input modes: .env file or single key/value pair. This clearly separates it from siblings like oneguard_secrets_edit, oneguard_secrets_generate, and oneguard_secrets_archive.

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 when to prefer from_env_file over direct value passing, and provides a specific cross-tool workflow: create a placeholder here, then call oneguard_secrets_generate for new generated values. The 'Never invent secret values' rule further constrains when invocation is appropriate.

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?

Annotations already provide readOnlyHint=false, idempotentHint=true, and destructiveHint=true. The description adds the key nuance that archiving is a soft deactivation, not a hard deletion, and that explicit user confirmation is required. This is genuinely useful context beyond the annotations, though it does not address reversibility or permission requirements.

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 with no filler; the main action and the critical caveats are front-loaded. 'It stops appearing as active but is not deleted' and 'Confirm with the user before calling' both earn their place. The description is appropriately 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 two-parameter mutation tool with full schema coverage and safety annotations, the description covers the essential semantics of archiving and the user-confirmation requirement. It does not state whether the action is reversible or what the response looks like, but these are secondary for this simple operation.

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 both parameters with meaningful descriptions, so schema description coverage is 100%. The tool description itself adds no parameter-level detail beyond what the schema already provides. The baseline score of 3 applies because 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 opens with the specific verb 'Archives' and the target 'a secret', and clarifies the state change by saying it stops appearing as active but is not deleted. This directly distinguishes the tool from the sibling oneguard_secrets_delete. The wording is specific enough for an agent to know what the tool does.

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 only usage instruction is 'Confirm with the user before calling,' which is a useful prerequisite but not an explicit when-to-use decision. It does not name alternatives such as oneguard_secrets_delete or oneguard_secrets_edit, nor does it state when archiving is preferable. The 'not deleted' wording weakly implies a contrast with deletion, but usage guidance remains 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.

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

Beyond the destructiveHint annotation, the description adds crucial behavioral context: deletion is permanent, cannot be undone, destroys everything stored in the secret, and requires a confirmation step. This meaningfully helps the agent understand the consequences and the required safety precondition.

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 focused sentences with no filler. The first sentence states the action and consequence, and the second provides the safety precondition. It is front-loaded and every sentence 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 simple destructive tool with fully documented parameters, destructive annotations, and clear usage and safety instructions, the description is complete. No output schema or nested structures require additional explanation, and an agent has enough context to invoke the tool correctly and safely.

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 covers all three parameters with clear descriptions, including the confirm parameter's exact-match requirement and its source. The tool description adds no additional parameter-level semantics, so the baseline score 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 names the action ('Permanently deletes') and the resource ('a secret and everything stored in it'), making the tool's core purpose unambiguous. It does not explicitly contrast with the sibling oneguard_secrets_archive, but the permanent and all-encompassing phrasing strongly distinguishes deletion from archival.

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 explicit conditions for use: only after the user has explicitly requested deletion of that specific secret, and after the secret name has been read back to the user. It does not explicitly mention alternatives like archiving, but the safety framing is clear enough for an agent to know when deletion is appropriate.

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?

Annotations already mark destructiveHint=true, and the description reinforces this with the concrete consequence that the whole payload is overwritten. It goes beyond the annotation by explaining the merge alternative and requiring user confirmation, giving the agent actionable context about the destructive 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 three sentences with no fluff. The critical destructive warning is front-loaded, and the alternative paths are compressed into a clear conditional. Every sentence 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 destructive mutation with seven parameters and no output schema, the description covers the key risks, names the alternatives, and states the user-confirmation requirement. Parameter details are handled by the schema, leaving the description to supply the missing decision context.

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 each parameter is already documented. The description adds valuable semantic context by explaining that key and value together form a replacement pair, and by positioning from_env_file as the preferred way to send the full set of variables, which helps the agent choose the right parameter combination.

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 opens with a specific verb and resource — 'Replaces a secret's stored payload' — and immediately clarifies the destructive scope by warning that a single key/value pair replaces every key. It also distinguishes this from merge-style siblings by naming oneguard_secrets_generate as the alternative.

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 explicit routing: for changing one variable while keeping others, use oneguard_secrets_generate (which merges) or sync to a .env file and push back with from_env_file. It also sets a clear precondition: 'Confirm with the user before calling this.' This tells the agent when to use the tool and when to choose an alternative.

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?

Goes well beyond the minimal annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) by disclosing the critical no-return guarantee ('WITHOUT returning the value'), the merge semantics (every other variable preserved), and the failure condition ('Fails if the key already exists unless force is true'). No contradiction: destructiveHint=false aligns with merge-not-replace 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?

Three dense sentences, each earning its place: the no-return guarantee is front-loaded in the first sentence, merge semantics and sibling comparison in the second, usage guidance in the third. No filler or repetition of schema 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?

Strong coverage of behavior, safety, and usage context for a write tool with 11 parameters and no output schema. The only gaps are the absence of any statement about what the tool returns on success/failure and no mention of auth requirements or rate limits. Minor given the depth of behavioral disclosure elsewhere.

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 contextual framing for 'key' (existence failure) and 'force' (override), but the schema already documents defaults, ranges, and charset options for the remaining parameters. The description adds little 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?

States a specific action with verb and resource: 'Generates a random value and stores it in a secret under the given key.' The explicit contrast with oneguard_secrets_edit and the use-case framing ('new password, token or key created for a service') clearly distinguish it from sibling tools in the same domain.

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?

Provides explicit when-to-use guidance: 'Use this whenever the user wants a new password, token or key created for a service.' It names the key sibling alternative (oneguard_secrets_edit) and explains the merge-vs-replace difference. However, it does not contrast with the equally similar siblings oneguard_generate or oneguard_secrets_add, leaving exclusion guidance incomplete.

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?

Annotations already declare readOnlyHint=true, and the description adds valuable behavioral context: 'Values are never returned by any tool in this server,' preventing a false expectation that secret values might be retrievable. It also states the exact output fields, going beyond the annotated safety profile.

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 one concise sentence that leads with the action, specifies the result fields, and closes with a high-value caveat about secret values. Every part 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 simple list tool with one fully documented parameter and read-only annotations, the description covers the purpose, the input, the output fields, and the important limitation that values are never returned. Nothing essential for correct invocation is missing.

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 only parameter, vault, is already documented as 'Vault id or its 8-character prefix.' The description does not add further parameter-specific meaning, 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 uses a specific action and resource: 'Lists the secrets of a vault', and names the returned fields (id prefix, name, archived). It clearly distinguishes from sibling tools like oneguard_vault_list, which lists vaults rather than secrets, and from secrets mutation tools.

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 context for using the tool is clear: call it to list secrets for a vault. However, it does not explicitly mention when not to use it or point to alternatives, such as oneguard_secrets_add or oneguard_vault_list.

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?

Annotations already declare readOnlyHint and openWorldHint, and the description adds context beyond that by naming the session/initialization state it checks and whether the API key may write. It is clearly non-mutating with no contradiction; exact response shape is omitted, but the core behavior is transparent.

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, each carrying distinct information: verification checks/return values and usage timing. The description is front-loaded with the action and resource, and contains no 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 parameterless read-only status tool with annotations, the description covers purpose, key return values, and invocation timing. It does not specify exact output field names/types, but given the absence of an output schema, what it provides is sufficient for an agent to 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?

The tool has zero parameters and schema coverage is 100%, so the baseline is 4. No parameter explanation is needed, and the description appropriately focuses on behavior and output rather than input.

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 ('Verifies') and resource (OneGuard connection) with three concrete checks: CLI installed, session initialized, and backend reachable. It also describes the return value, making it easy to distinguish this health-check tool from sibling tools like oneguard_init or oneguard_env_status.

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?

Provides explicit when-to-use guidance: 'Use this first when something is not working, or before a batch of changes.' It does not list when-not-to-use or alternative tools, 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?

The description clearly discloses that this sends a real email to a real person and grants organizational access upon acceptance. These real-world side effects go well beyond what the annotations (readOnlyHint=false, destructiveHint=false) convey, and there is no contradiction.

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, no waste. The core action is stated first, followed by the key behavioral warning and the invocation guardrail. Every sentence 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 simple two-parameter tool with full schema coverage and no output schema, the description is complete. It covers the action, the side effects, the access implications, and the critical condition for calling it. Nothing essential is missing.

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 baseline is 3. The description adds extra meaning to the email parameter by stressing that it must be the exact address the user gave, which prevents guessing or autocomplete behavior. Role semantics are already fully covered by the schema enum.

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 action (sends an invitation) on a clear resource (the organization) with a concrete outcome (grants access once accepted). It clearly distinguishes this from sibling team tools like oneguard_teams_list, oneguard_teams_set_role, and oneguard_teams_remove.

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 explicit invocation guardrails: only call it when the user explicitly asked, and only with the exact address they provided. This directly prevents misuse by autonomous agents, which is especially valuable for an action that emails a real person and grants access.

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?

Annotations already carry the safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower. The description adds useful context about output scope — organization members with roles and id prefixes — but does not disclose response format, ordering, or pagination 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?

A single ~20-word sentence that front-loads the verb and resource, states the scope, and captures the most decision-relevant output detail (the id prefix) with zero filler. Every word 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 zero-parameter read tool with no output schema, this is nearly complete: it states what is returned (roles and id prefixes) and implies the cross-tool use case. The only gap is the absence of any note on response format, but nothing an agent needs to invoke the tool correctly is missing.

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 baseline of 4 applies; the description has nothing to compensate for. The mention of the 8-character id prefix is helpful for parameterizing sibling team tools, and it tells agents what identifier format to expect, though it concerns other tools' inputs rather than this one's.

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 ('Lists') and resource ('the members of the organization') and goes beyond the title by specifying the exact output payload: roles and the 8-character id prefix. This clearly differentiates it from the mutating team siblings (invite, set_role, remove) and from the vault/secrets list tools.

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 explicit when-to-use or when-not-to-use guidance is given, and no alternative tool is named. Usage context is implied through the phrase 'the 8-character id prefix other team tools accept,' which signals this tool is the identifier source for the team mutation tools, but the connection is left to inference.

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?

Annotations already mark it destructive, but the description adds meaningful context: revocation covers every secret in the organization and is irreversible, requiring re-invitation. This goes beyond the structured annotation by specifying scope and permanence.

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 compact sentences: action and consequence first, irreversibility second, and the usage guardrail third. Every sentence earns its place with no redundant wording.

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 two-parameter destructive tool with full schema descriptions and a destructive annotation, the description covers the action, consequences, irreversibility, and the agent's go/no-go condition. No output schema means return-value documentation isn't required.

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 both member and confirm are already well described in the input schema. The description's phrase about reading the email back reinforces the confirm parameter's purpose but doesn't add new parameter semantics 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 states a specific verb and resource: removes a member from the organization and revokes access to every secret. This clearly distinguishes it from sibling tools like oneguard_teams_invite and oneguard_teams_set_role.

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 gives an explicit go/no-go condition: only call after the user explicitly asked for this specific person to be removed, and read their email back first. It does not name alternative tools for non-removal scenarios, so it lacks explicit alternative routing.

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?

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses two important behavioral traits: promoting to owner/admin grants broad access to every secret, and admin callers are blocked from modifying owners, other admins, or promoting to admin/owner. These are security-relevant consequences not encoded in the annotations and are essential for safe usage.

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 three sentences, each earning its place: the main action, a safety warning, and a key permission constraint. It is front-loaded with the primary purpose and avoids filler. This is appropriately sized for the tool's complexity.

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 (2 params, no output schema), the description is complete. It covers the operation, parameter identification, privilege escalation consequences, and admin restrictions. No critical information an agent needs to invoke the tool correctly is missing.

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 covers 100% of parameters with descriptions: role enums and member email/id prefix. The description repeats the member identification format but adds no additional parameter semantics. Per the rubric, with full schema coverage the baseline is 3, and no extra value is provided here.

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 opens with a specific verb and resource: 'Changes an existing member's role in the organization.' This clearly distinguishes it from sibling tools like invite, remove, and list. It also implicitly conveys the operation's scope (role mutation), so an agent can select it correctly without opening the schema.

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 clear context about when to use the tool and adds critical operational guidance: confirm with the user before granting owner/admin, and warns about caller limitations. It does not explicitly name alternatives such as invite or remove, but the sibling names and the verb 'change' make the appropriate use case unambiguous.

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?

Annotations already mark readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds that it returns an id and explains the vault concept, which is useful context, but it does not disclose side effects, permissions, or failure behavior. Minimal extra value beyond annotations.

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, no filler. The action and return value are front-loaded in the first sentence, and the second sentence provides necessary domain context without 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 creation tool with one parameter and no output schema, the description covers the core purpose and return value. It does not mention uniqueness or permission requirements, but these are not critical for an agent to call it correctly. Slightly more context (e.g., uniqueness) could be added, but current coverage 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%: the only parameter 'name' has a clear description. The tool description adds no additional constraints, format, or meaning beyond the schema. 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 uses a precise verb ('Creates') and resource ('a new vault'), and clarifies what a vault is ('container that secrets live in'), distinguishing it from sibling tools like vault_list and vault_rename. The purpose 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 implies when to use the tool (when you need a container for secrets) but does not explicitly mention alternatives or state when not to use it. No exclusion or routing to other vault tools is provided, so usage 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.

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

Annotations already indicate readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds useful behavioral context beyond that: it specifies the output includes the 8-character id prefix and defines a vault as a container for secrets. This helps the agent understand what to expect without contradicting annotations.

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 exactly two sentences, front-loaded with the main action, and each sentence adds necessary information without redundancy. It avoids any filler or repetition, earning a perfect score.

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 read-only listing tool with no parameters and no output schema, the description covers all essential information: it lists all vaults, explains the id prefix usage, and clarifies what a vault is. There are no missing prerequisites or expectations that would leave an agent uncertain about calling it.

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 has no parameter semantics to explain. The baseline for 0 params is 4, and the description's mention of output format (id prefix) does not relate to parameters but is still informative. No deduction 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 states a specific action (lists every vault) and resource (vaults in the organization), and adds the key detail that it returns the 8-character id prefix accepted by other tools. This clearly distinguishes it from siblings like oneguard_secrets_list or oneguard_vault_add, which have different purposes.

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 its use when you need to enumerate all vaults or obtain their IDs, which is evident from the context. However, it does not explicitly mention when not to use it or point to alternatives (e.g., 'for secrets use oneguard_secrets_list'). The clarity of the operation makes this a minor omission, so a 4 is appropriate.

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?

Annotations already indicate a mutating but non-destructive, idempotent operation. The description adds specific behavioral context: secrets, links, and ids remain unchanged, so callers know the operation is safe and scoped. This goes beyond what annotations alone convey.

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 short sentences, no filler. The core action is stated first, and the most important side-effect clarification follows immediately. Everything present 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 simple two-parameter rename operation with no output schema and no nested structures, the description fully covers what the tool does and what side effects to expect. An agent has enough context to select and invoke 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 100%, with both vault and name clearly documented in the input schema. The tool description doesn't add extra parameter meaning, but the schema already carries the needed semantics, so the baseline 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?

The description uses a specific verb ('Renames') with a clear resource ('an existing vault') and clarifies the exact scope: only the display name changes. This distinguishes it from sibling tools like oneguard_vault_list or oneguard_vault_add without needing to inspect schemas.

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 phrase 'existing vault' implies this tool is for updating an already-created vault, not creating one, but no explicit guidance compares it to vault_add/vault_list or states when not to use it. The usage context is implied rather than stated.

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