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

Annotations already declare readOnly/idempotent/non-destructive. The description adds 'verified' records and explicitly states that command bodies and credentials are never included, which is meaningful behavioral context beyond the safety hints. It does not contradict 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, front-loaded with the primary action, followed by a useful clarification. No redundant or extraneous content; 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?

With four optional parameters and no output schema, the description is incomplete. It covers the content type but leaves filtering semantics and return structure unexplained, making correct invocation uncertain for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description provides no explanation of the parameters jobId, limit, since, or action. An agent cannot infer what these parameters control or how to use them, so the description completely fails to compensate for the lack of schema hints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool queries verified RunBeacon audit records, with a specific verb ('Query') and resource ('audit records'). It is distinguishable from sibling tools like job_list and credential management, 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?

Implies use for accessing audit metadata and clarifies that content excludes commands/credentials, but it does not explicitly state when to use this tool versus alternatives. There is no mention of typical scenarios or exclusions, so guidance is only incidental.

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 the tool as idempotent and non-destructive. The description adds specificity by clarifying that the profile and OS-managed secret are preserved, giving a clearer behavioral contract beyond 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?

The description is one sentence, front-loaded with the verb 'Clear,' and contains no redundant information. Every word contributes to understanding the tool.

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 a single enum parameter and no output schema, the description fully covers the tool's purpose and key constraint (non-deletion). It is complete and sufficient for an agent to invoke 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 single 'kind' parameter is explained by the description's 'SSH or GitHub' reference, which directly maps to the enum values. Since the schema has no descriptions and coverage is 0%, this compensation is essential and effective.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (clear) and resource (default SSH/GitHub credential profile), and differentiates from the sibling delete tool by explicitly noting it does not delete the profile or secret.

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 (to clear a default while preserving the profile) and provides an exclusion by stating 'without deleting the profile or any OS-managed secret.' It does not explicitly name alternatives, but the context makes the use case clear.

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 adds valuable context beyond the destructiveHint annotation by clarifying exactly what is NOT deleted (ssh-agent keys, private-key files, Git Credential Manager credentials). This precisely scopes the destructive behavior, which is important for a delete operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences, front-loaded with the action and immediately followed by a crucial clarification. No unnecessary words 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 simple single-parameter delete tool with destructive annotations, the description adequately covers the core purpose and scope of deletion. However, it lacks any explanation of the 'id' parameter or how to find the profile ID, which is a minor gap given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the 'id' parameter. It does not explicitly explain what 'id' refers to or how to obtain it (e.g., from credential_profile_list). The meaning is only inferred from the tool name, which is insufficient for a low-coverage 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 'Delete one RunBeacon credential reference profile' with a specific verb and resource. This distinguishes it from sibling tools like credential_profile_save, credential_profile_list, and other delete tools such as ssh_password_delete and github_token_delete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context by explaining that this tool only deletes the reference profile, not underlying credentials, implying it should be used when you want to remove the profile without affecting stored credentials. However, it does not explicitly name alternative tools or provide when-not-to-use scenarios.

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 destructiveHint=false, covering the safety baseline. The description adds a valuable guarantee that results never include secrets, which informs how the agent can safely use the output. This goes beyond the annotations, though no other behavioral details like pagination are provided.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no unnecessary words. It communicates the core function and safety guarantee efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and the read-only annotations, the description is largely sufficient. However, the missing explanation of the 'kind' parameter and the lack of an output schema leave some gaps in understanding the full behavior and response format.

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 includes one optional parameter 'kind' with enum values (ssh, github), but the description does not mention it at all. With 0% schema description coverage, the description fails to explain whether 'kind' filters results or how to use it, leaving the parameter semantically ambiguous.

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 with a specific verb ('List') and resource ('credential reference profiles'). The qualifiers 'safe' and 'never contain secrets' further distinguish it from sibling tools like credential_profile_save or credential_profile_delete.

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 intended use is implied (to enumerate credential profiles), but there is no explicit guidance on when to prefer this tool over alternatives like credential_profile_save or credential_profile_set_default. No exclusions or alternative comparisons 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?

The description adds critical behavioral context beyond the annotations: it explicitly states that secret material is rejected and never persisted, and clarifies that GitHub profiles reuse Git Credential Manager. This is valuable disclosure for a tool that could be mistaken for a secret-storage mechanism.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no fluff. The first sentence front-loads the core purpose, and the second adds necessary detail about SSH vs GitHub behavior and secret rejection. 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 13-parameter tool, the description plus a rich schema (77% parameter coverage) provides a solid understanding. It covers the fundamental distinction from secret-saving tools and outlines profile behavior, though it doesn't detail update semantics or every optional parameter. Still, it is complete enough for safe use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers 77% of parameters, so the baseline is 3. The description adds meaningful semantics by explaining the overall storage model (SSH stores host/user/key-verification/agent-or-key path; GitHub uses Git Credential Manager), which helps disambiguate the purpose of related parameters like privateKeyPath and credentialSource.

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 ('Create or update') and a specific resource ('passwordless credential reference profile'). It clearly distinguishes the tool from siblings like ssh_password_save and github_token_save by emphasizing it stores only references, not actual secrets.

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 for when to use the tool by explaining what SSH profiles and GitHub profiles do, and explicitly states that passwords, passphrases, private-key contents, and tokens are rejected. It does not name alternative tools explicitly, but the exclusion of secrets is a strong usage guideline.

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

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

The description adds meaningful behavioral context beyond the annotations (which already flag it as non-read-only, idempotent, non-destructive). It explicitly states what the tool does NOT do ('does not alter OS-managed secrets') and states the narrow scope ('changes only RunBeacon profile selection'), which helps the agent understand side effects and safety. No contradictions with 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 two sentences, with the first sentence front-loading the primary action and scope, and the second sentence adding a concise safety clarification. There is no repetition or filler; every clause 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 one-parameter mutation tool with useful annotations and no output schema, the description provides sufficient context: it explains what the default affects, independence between kinds, and exclusion of OS-managed secrets. It could mention error cases or prerequisites (e.g., profile must exist), but given the schema and idempotentHint, it 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?

The single parameter 'id' is fully described in the schema with 'Existing SSH or GitHub credential profile id.' The description adds contextual meaning ('existing', 'for its kind') but does not add details beyond the schema. 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 uses a specific verb ('Make existing ... default') and a clear resource ('credential profile'), with the scope 'for its kind' and the clarification that SSH and GitHub defaults are independent. This unambiguously differentiates the tool from siblings like credential_profile_clear_default and credential_profile_delete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies when to use this tool (to set an existing profile as default) and gives important context: SSH and GitHub defaults are independent, and it only affects RunBeacon profile selection, not OS-managed secrets. It does not explicitly name alternative tools for clearing or deleting defaults, but the usage context is clear enough for selection.

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 lists 'delete' as an action, which is destructive, but the annotations set destructiveHint to false. This is a direct contradiction, making the behavioral profile misleading. No additional behavioral context (e.g., persistence details, side effects) is provided to resolve the conflict.

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 with no filler. The first sentence front-loads the action and resource, while the second adds a critical detail about environment-variable references. Every word 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?

For a tool with 6 parameters, no output schema, and conflicting annotations, the description is not complete. It lacks parameter-level explanations, action semantics, prerequisites, and return values, and the contradiction with destructiveHint further reduces completeness.

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?

With 0% schema description coverage, the description was expected to compensate. It partially explains urlEnvVar and hmacSecretEnvVar by mentioning environment-variable references, but it leaves other parameters (id, kind, enabled, action) without any semantic guidance beyond the enum values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies the exact verbs (list, save, delete) and the resource (persistent Codex, desktop, and HMAC HTTPS webhook subscriptions). This clearly distinguishes it from sibling tools focused on credentials, jobs, and policies.

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 for managing webhook subscriptions and notes the environment-variable reference pattern, but it does not explicitly state when to use this tool over alternatives or provide exclusions. The presence of sibling tools offers context, but the description itself lacks direct 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 mark this as destructive and non-idempotent. The description adds important behavioral details: it only commits already-staged changes, pushes without force, and monitors in the background. It also mentions the never-runs-git-add rule, giving the agent a clear mental model beyond 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?

The description is two sentences, front-loaded with the core action, and every phrase adds value. It packs the key workflow, safety constraint, and cross-tool referral without 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?

While the description explains the high-level process, it does not clarify what the tool returns (e.g., a job ID) or how the agent should interpret the outcome. Given there is no output schema, the missing return-value information is a notable gap, though the instruction to use job_wait partially compensates by implying a follow-up mechanism.

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 83% of parameter descriptions, so the baseline is 3. The description adds context around the commitMessage and remote parameters by mentioning 'commit already-staged changes' and 'push without force', but it doesn't substantially augment the schema's parameter documentation.

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 starts a dashboard-tracked GitHub publish process: optionally commit staged changes, push without force, and monitor GitHub Actions in the background. This distinguishes it from sibling tools like job_start by specifying the GitHub publish workflow and the key constraint of never running git add.

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 practical usage guidance: 'This never runs git add' clarifies an important limitation, and 'Use job_wait once if the workflow should continue automatically after publishing' directs the agent to a specific next step. It does not explicitly list when to use alternatives, but the workflow context and sibling hints give clear enough direction.

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 convey destructive intent (destructiveHint: true). The description adds valuable context: it states exactly what is removed (credential helper entry and RunBeacon profile reference) and the limitation regarding generic profiles. It does not mention potential remote effects (e.g., whether the PAT is revoked on GitHub), but given the annotation coverage, this is sufficient.

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, front-loaded with the action, and every clause adds valuable information. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple one-parameter delete tool with annotations covering safety and a schema covering parameters. The description is complete for an agent to select and invoke it correctly, explaining the exact targets and the exclusion. No output schema exists, so no return-value explanation is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides 100% coverage for the single parameter 'id' with description 'RunBeacon GitHub PAT profile to delete'. The tool description restates this in prose but adds no additional semantic meaning beyond what the schema provides. 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 clearly states the action ('Delete a GitHub PAT created through github_token_save') and specifies the scope and mechanism ('from the configured Git credential helper and remove its RunBeacon profile reference'). It also distinguishes itself from generic deletions with the caveat 'This cannot delete generic OAuth/login profiles', making it distinct from sibling tools like credential_profile_delete.

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 scopes usage to GitHub PATs created via github_token_save, and explicitly excludes generic OAuth/login profiles, providing a clear when-not. It implies the correct alternative for generic profiles without naming a tool, but the boundary is 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?

The description adds a crucial safety guarantee: 'The token is never written to RunBeacon profiles, jobs, dashboard state, or logs.' This goes beyond the annotations' idempotent and non-destructive hints by explaining where the token is and is not stored, enhancing trust and predictability.

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 concise sentences with no filler: the first states the core action, the second gives parameter preference, and the third states a safety guarantee. Front-loaded and easy to scan.

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 purpose, parameter selection, and storage safety. Although there is no output schema or explicit return-value explanation, this is acceptable for a save operation. A note on success/failure response would improve completeness, but the core context is well covered.

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 83%, and the description adds valuable decision guidance by prioritizing tokenEnvVar over token, explaining the security rationale. This helps the agent choose the correct parameter beyond the schema's per-field 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 opens with 'Store a GitHub personal access token in the configured Git credential helper and create a safe RunBeacon profile reference,' using a specific verb, resource, and outcome. This clearly differentiates it from sibling tools like github_token_delete and credential_profile_save.

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 explicitly instructs to 'Prefer tokenEnvVar so the token never appears in conversation; use token only when the user explicitly provides it,' providing clear parameter-level guidance. It does not name alternative tools, but the preference is actionable and sufficient for most scenarios.

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 destructiveHint=true and idempotentHint=true, so the description is not required to restate destructiveness. It adds useful state context ('queued or running'), but does not disclose what happens after cancellation (e.g., whether state changes are permanent, or if any cleanup occurs). No contradiction with 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 a single, front-loaded sentence that conveys the essential purpose and scope without any filler. Every word earns its place, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity (one required parameter), rich annotations (destructive, idempotent), and no output schema, the description is largely complete for basic usage. It specifies the valid target states. However, it does not describe post-cancel behavior or error scenarios, which would make it fully complete for a destructive tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain jobId beyond implying it identifies the job to cancel. No format, source, or validation details are provided. With a single parameter, the meaning is inferable but the description itself adds minimal semantic value.

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 'Cancel' with a clear resource 'queued or running tracked job', making the tool's purpose immediately understandable. It also distinguishes this from sibling tools like job_start, job_list, and job_watch by specifying the action on existing tracked jobs.

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 states exactly when to use the tool: for jobs that are queued or running. It implies it should not be used for completed jobs, but it does not explicitly name alternatives or provide a when-not-to-use clause. Clear context, but lacks explicit exclusions.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description reveals that the dashboard long-polls job_watch, that updates do not create model turns, and that job history is not exposed. This is valuable behavioral context not present in the structured 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?

Three short sentences, each carrying non-redundant information: core function, parameter behavior, and polling transparency. The content 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 tool with one optional parameter, no output schema, and strong annotations, the description is complete. It covers the primary function, the parameter's conditional behavior, and the key side-effect of not generating model turns or exposing history—enough for an agent 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?

The description greatly enriches the meaning of the single optional parameter: providing jobId reopens a known task, while omitting it selects the newest non-terminal task. The schema only states 'Tracked task to display without showing other jobs,' so the description adds concrete selection behavior.

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 'Render one live RunBeacon task,' naming a specific verb and resource. The subsequent sentence clarifies behavior with and without jobId, and the mention of long-polling job_watch distinguishes it from sibling tools like job_list or job_watch.

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 conditional guidance for the optional jobId ('Pass jobId to reopen a known task; without it, the newest non-terminal task is selected'). It also implies a UI-level use case by referencing job_watch, but it does not explicitly name alternative tools or state when not to use the dashboard.

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, destructiveHint=false, and idempotentHint=true, covering safety. The description adds the 'bounded output tails' behavior, which is useful context beyond the schema, but it does not disclose further behavioral details like return format or pagination, so it adds only moderate value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two tight sentences: the first states the primary purpose, the second gives usage guidance for an alternative. Every word earns its place, with no fluff or repetition of structural data.

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 list tool with no output schema and two self-explanatory parameters, the description covers the core functionality and points to the relevant sibling for live use. It could mention limit defaults or pagination, but those are visible in the schema, so the description 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 0%, so the description bears the burden of explaining parameters. The phrase 'bounded output tails' hints at tailLines, but it does not explain 'limit' or provide any additional semantics beyond what the parameter names imply. Given the low coverage, this is insufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('List') and resource ('tracked job history'), and adds 'bounded output tails,' which clarifies the tool's scope. It also distinguishes itself from the sibling job_watch by directing live-dashboard use to that tool, making its purpose 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 explicitly names job_watch as the alternative for live dashboards, giving a clear exclusion for this tool. However, it does not explicitly state when to use job_list beyond the implicit 'when you need tracked job history,' which is slightly less direct than a full when/when-not pair.

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, idempotentHint=true, and destructiveHint=false, which cover the safety profile. The description adds value by revealing the 'bounded output tail' behavior and the 'one tracked job' scope, which are not in the annotations. This enriches the agent's understanding without contradicting the structured metadata.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with the core action, and no fluff. Every word earns its place, including the usage caveat and alternative tool mention. This is a model of efficient description writing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool with two parameters, rich annotations, and sibling context, the description covers purpose, scope, and usage differentiation. It lacks details about return format or error behavior, but given the presence of annotations and bounded output mention, it is sufficiently complete for the tool's simplicity. It doesn't explain what a 'snapshot' contains beyond the output tail, but this is a minor gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It indirectly covers 'jobId' via 'one tracked job' and 'tailLines' via 'bounded output tail'. However, it doesn't explain defaults, bounds, or data types that the schema already contains, and the connection is implicit rather than explicit. This is adequate but not comprehensive.

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 ('Read') and clearly identifies the resource ('one tracked job') and output ('bounded output tail'). It distinguishes from siblings by specifying 'one' job, versus job_list or job_wait. The mention of 'job_wait' as an alternative further clarifies its unique 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?

Explicitly states when to use ('only for explicit status requests') and provides an alternative ('prefer job_wait for completion'). This gives clear direction on choosing this tool over its sibling job_wait, satisfying both when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructive/write behavior, and the description does not contradict them. It adds useful behavioral context about idempotent retry via requestTraceId, verbatim command pass-through, and the default-credential fast path, which aids the agent beyond the safety flags.

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 carrying actionable information, front-loaded with the primary purpose. 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?

Given the tool's complexity (20 params, nested target objects, no output schema), the description covers the most critical operational scenarios: retry idempotency and the default SSH fast path. It doesn't enumerate every parameter, but the schema handles those; the description provides the decision context an agent needs.

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?

With schema coverage at ~70%, the description adds meaning to key parameters: requestTraceId reuse semantics, useDefaultCredential direct path, and remote command escaping behavior. While not covering all 20 parameters, it enriches those that are most likely to cause misuse.

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 'Start one tracked local or SSH command,' which is a specific verb+resource that distinguishes it from sibling job tools like job_cancel or job_list. It clearly communicates the core action without ambiguity.

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 directives: pass remote commands verbatim, reuse requestTraceId on retries, and set useDefaultCredential=true to skip profile listing. It names a specific alternative (credential_profile_list) and explicitly says 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, idempotentHint, and destructiveHint, providing safety context. The description adds valuable behavioral detail not in annotations: it is event-driven, waits server-side, consumes no model turns, and should be called right after job_start. This goes beyond the structured hints without contradicting them.

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 only two sentences, front-loaded with the core behavior and followed by a succinct usage directive. Every word earns its place; no fluff 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?

The description covers the core waiting behavior and usage context well, but with no output schema it omits details like return format, what happens on timeout, and what constitutes a 'terminal state' (success, failure, cancellation). Sibling tools like job_watch remain somewhat ambiguous relative to this one.

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 only 33% (only timeoutMs has a schema description). The description does not explain jobId (e.g., that it comes from job_start) or tailLines (what it controls), nor does it add meaning for those parameters. This gap is not compensated by the tool description.

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 with a specific verb and resource: 'Wait inside the MCP server until a tracked job reaches a terminal state.' It also distinguishes itself from sibling tools like job_watch by emphasizing that it is event-driven and consumes no repeated model turns while waiting, making its unique purpose clear.

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 usage guidance: 'Call it immediately as the next tool call after job_start, without intermediate commentary, profile listing, status checks, or extra planning.' This provides a clear when-to-use context and excludes certain actions, but it does not name alternative tools for comparison 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds behavioral context by calling it a 'long-poll endpoint' and specifying it waits for 'one job version change' rather than terminal completion. This is useful beyond the annotations, though it doesn't mention timeout or return format.

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 filler. The first sentence states the core action, and the second provides essential usage differentiation. 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?

The description excels at tool selection and sibling differentiation, and annotations cover safety. However, with four parameters and no output schema, the lack of parameter explanation and return behavior leaves the agent to infer too much for correct invocation. It is 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 description coverage is 0%, so the description must compensate, but it does not explicitly explain any parameters. It only hints at the meaning of afterVersion through 'version change.' The roles of tailLines and timeoutMs are left entirely to the schema, which provides no 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 clearly states the tool's function: 'Wait for one job version change.' It uses a specific verb and resource, and explicitly distinguishes itself from sibling job_wait by noting this is for the RunBeacon dashboard while models should use job_wait for terminal completion.

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 usage guidance: it is intended for the RunBeacon dashboard, and models should use job_wait for terminal completion. This directly tells when to use this tool versus an alternative, fulfilling the 'when/when-not/alternatives' criterion.

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 destructiveHint and idempotentHint, but the description adds a meaningful limitation (no job approval) and clarifies that the tool works on policy defaults. It goes beyond structured data 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 two sentences, front-loaded with a clear verb+resource summary and immediately followed by a critical usage constraint. No redundant or extraneous 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?

The tool has 4 parameters, a nested object, and no output schema, yet the description omits details about parameter behavior, default values, or return information. While purpose is clear, the lack of parameter context makes the tool hard to invoke correctly without external knowledge.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it only explains the action (get/update) and ignores parameters like confirm, requireApproval, and approvalTtlSeconds. Parameter names are somewhat self-explanatory, but no additional meaning is provided.

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 'Read or update risk policy defaults,' naming the resource and supported actions. It also explicitly differentiates this tool from job approval, aligning with sibling tools like job_start and distinguishing its 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 provides explicit when-not-to-use guidance: 'This tool cannot approve a job,' and names alternatives ('local dashboard or interactive CLI'). This clear exclusion helps an agent choose the right tool for job approvals versus policy management.

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 destructiveHint=true and readOnlyHint=false, so the description does not need to restate those. It adds context about signed release assets and CLI installer behavior, which is useful. However, it does not disclose behavior for uninstall or migrate-host-key, which are potentially destructive or state-changing actions not covered by 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 two sentences with no redundancy. The first sentence is a clear, front-loaded purpose statement; the second adds relevant operational context without wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (5 actions, a nested target object, and no output schema), the description is incomplete. It covers only 'probe' and a note about install/upgrades, omitting migrate-host-key, uninstall, confirm semantics, credential profiles, and any description of return values or state changes.

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 only 40%, and the description does not compensate for undocumented parameters like action, confirm, credentialProfile, or useDefaultCredential. The phrase 'saved SSH profile' is not tied to specific fields, and no parameter-level meaning is added beyond what the schema already provides.

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 identifies the tool's primary verb-resource pair ('Probe the durable Runner through a saved SSH profile') and distinguishes it from sibling tools focused on policies, credentials, or jobs. However, it omits mention of other actions like migrate-host-key and uninstall, and the note that 'Installation and upgrades require a signed release asset and are performed by the CLI installer' could confuse users about whether the tool itself can perform those 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 offers no explicit guidance on when to use this tool versus alternatives such as credential_profile_save or ssh_password_save. The phrase 'through a saved SSH profile' implies a prerequisite, but there is no stated context, exclusions, or comparison to sibling tools.

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

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

Annotations already flag destructive behavior, but the description adds meaningful details: it removes the password from the OS credential helper, removes the RunBeacon profile reference, and rejects passwordless SSH profiles. This goes beyond the annotations and explains actions and constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the action and resource, followed by essential behavioral details. Every phrase 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?

For a simple one-parameter destructive tool with no output schema, the description fully covers what will happen (deletion from OS helper and profile reference), the precondition (created via ssh_password_save), and an important constraint (passwordless profiles rejected). No return format is necessary given the lack of output 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?

The schema already provides 100% coverage for the single required parameter 'id' with a clear description. The description adds that passwordless profiles are rejected, which is relevant but not directly about parameter format. The baseline of 3 is appropriate given complete 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 states a specific action ('Delete') on a specific resource ('SSH password created through ssh_password_save') and clearly distinguishes the scope by mentioning the source and the additional removal of the RunBeacon profile reference. This makes it distinct from broader deletion tools like credential_profile_delete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly implies this tool is for deleting SSH passwords created via ssh_password_save, providing context for when it applies. However, it does not explicitly name alternative tools or state when not to use it, which would have warranted 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 goes well beyond annotations by disclosing that the password is never written to profiles, jobs, dashboard state, logs, command arguments, or environment metadata, and that it stores only specific fields in the RunBeacon profile. This is valuable behavioral context not present in 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 three sentences, front-loaded with the primary action, followed by a security-critical detail. 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?

The description gives a clear behavioral model of what is stored and what is not, which is sufficient for a save operation. However, it omits any mention of return values or success indication, and the lack of an output schema leaves some ambiguity, though not critical.

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 91%, so the input schema already describes parameters well. The description adds little beyond restating the preference for passwordEnvVar and the memory-only nature of password, which are already in the schema 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 clearly states a specific verb+resource: 'Store an SSH password' and 'create a safe RunBeacon profile'. It distinguishes from siblings like ssh_password_delete and github_token_save by focusing on SSH password storage and its unique profile contents.

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 vs alternatives such as credential_profile_save or github_token_save. The only usage guidance ('Prefer passwordEnvVar') concerns parameter selection, not tool selection.

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