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

Annotations already declare readOnlyHint=true, and the description's 'Describe' wording is consistent with that read-only behavior. The description adds only a small amount of context about the output coverage (capabilities and tool groups) but does not disclose additional behavioral traits such as permissions or response structure; however, an output schema exists and the safety profile is already 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 a single, front-loaded sentence with no filler words. Every word contributes to conveying the tool's purpose, making it easy to scan and parse.

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 introspection tool with an output schema available, the description is largely sufficient to select and invoke the tool correctly. It could be slightly more complete by indicating when the agent should use it, such as when discovering available capabilities, but nothing essential to making the call 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, and the empty schema fully reflects that. With no parameters to explain, the description does not need to add parameter-level meaning; the baseline for zero-parameter tools is appropriate.

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

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

The description clearly states the verb (Describe) and the resource (Adios agent capabilities and tool groups), so an agent can understand this is an introspection/capabilities tool. It does not explicitly contrast it with any sibling, but the scope is distinct enough from the workspace/repository tools in the sibling list.

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

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

There is no guidance about when to invoke this tool, how it should fit into an agent workflow, or which alternative tools might serve a similar purpose. The description simply states what the tool does, not when it is appropriate to use.

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 this is a write operation (readOnlyHint=false) but not destructive (destructiveHint=false). The description adds 'append' and 'current agent session' context and lists event categories, which is useful, but it does not disclose further behavioral details such as whether events are persisted, whether they appear in session history, or any rate/visibility implications. There is 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 communicates the operation, scope, and event categories with no filler. Every word adds value, and the mention of 'compact' helps set expectations about event size.

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

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

Given the simple append operation, the fully documented input schema, and the presence of an output schema, the description is largely sufficient. It could be slightly more complete by clarifying when to use this versus plan-update tools, but the essential context for invoking the tool correctly is present.

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 each parameter clearly described, including examples for event_type and optional agent_run_id/agent_plan_id. The description does not add parameter semantics beyond the schema, but it does not need to because the schema already carries the full explanatory burden; 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 verb ('Append') with a clear resource ('event to the current agent session') and enumerates the kinds of events it handles (progress, tool, test, browser, approval, deployment). This makes it immediately distinguishable from sibling tools like save_agent_plan or update_agent_plan_step, whose purpose is plan management rather than event logging.

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: this tool is for appending events to the current agent session. It does not explicitly state when to avoid this tool or mention alternatives, but the 'current agent session' framing and event-type list provide enough contextual guidance for the primary use case.

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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the 'authenticated' qualifier, which signals dependence on the current session, and clarifies the Adios-specific nature of the principal. No error behavior or preconditions beyond authentication are disclosed.

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

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

The description is a single, front-loaded sentence with no filler or redundant information. Every word contributes to the meaning.

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 introspection tool with one optional, well-documented parameter and an output schema, the description provides enough information for correct selection and invocation. The remaining details, such as the meaning of Adios principal, are either domain knowledge or captured in the 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?

Schema description coverage is 100% for the single optional team_id parameter, so the schema fully documents it. The description adds no parameter-level detail beyond what the schema already provides, warranting the baseline score of 3.

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

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

The description uses a specific verb ('Return') and names a precise resource ('current authenticated Adios principal and team context'). It clearly distinguishes itself from sibling tools, none of which appear to target authentication context.

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 for retrieving the caller's identity and team context, but it does not explicitly state when to use it versus alternatives. No sibling directly competes, so the context is inferable, but explicit guidance is missing.

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 flag destructiveHint=true and readOnlyHint=false, but the description adds none of the beyond-annotation context that matters: what gets overwritten or destroyed, whether the build mutates workspace state, or what side effects occur. Saying 'Build an artifact from workspace contents' only restates the operation without explaining its behavioral consequences.

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 wasted words or redundant phrasing. It is concise, though the brevity contributes to the vagueness of 'artifact.'

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?

Despite having output schema and annotations, the description leaves out the artifact type, the relationship to build_workspace_dev, and any caution about the destructive nature. For a mutation-oriented build tool among many workspace siblings, this is not enough context for reliable selection and 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?

Schema coverage is 100%, and both team_id and workspace_id already have clear descriptions in the schema, so the baseline applies. The description adds no extra parameter meaning beyond implying the workspace contents are the source.

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 ('Build') and names a resource ('artifact from workspace contents'), so an agent can tell this is a build action. However, 'artifact' is never defined and the description doesn't distinguish this tool from the sibling build_workspace_dev, leaving the exact deliverable ambiguous.

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 choose this tool over build_workspace_dev, deploy_workspace, or prepare_workspace_preview. There are no prerequisites, exclusions, or context signals such as 'use this to create a compiled artifact before deploying.'

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 the operation as destructive and non-read-only. The description adds valuable behavioral context: it is asynchronous, queues the command, returns a command_id immediately, and requires polling for progress. It does not spell out the destructive effects themselves, but the annotations cover the safety signal.

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, zero filler. The first sentence states the action and return, the second gives the essential follow-up. Every word contributes, and the key information is front-loaded.

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

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

With a full output schema and annotations, the description does not need to explain return fields or safety profile. It even names the polling tools to use after. The main gap is the missing distinction from the build_workspace sibling, which is a real contextual omission given the sibling list.

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

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

Schema description coverage is 100%, and both parameters have clear descriptions ('The ID of the team', 'The workspace ID'). The tool description does not add extra meaning to the parameters, which is acceptable because the schema already carries the semantic weight. 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 states a specific verb ('Queue'), a clear resource ('the canonical workspace build command'), and an explicit return value ('command_id'). This is clear and actionable. However, it does not explain how build_workspace_dev differs from the sibling build_workspace, leaving some ambiguity for an agent choosing between them.

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

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

The description clearly states the immediate follow-up pattern: poll get_workspace_command_status and get_workspace_command_logs. But it does not specify when to use this tool instead of alternatives like build_workspace or run_workspace_command, nor does it state any exclusions. Usage context is implied but not 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 mark the tool as readOnly and non-destructive, and the description's 'Check' aligns with that. The description adds the categories of findings covered, but it does not disclose additional behavioral details such as failure modes or whether it performs any side-effect-free scans across the workspace.

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 with no filler. It front-loads the action and resource, then includes the key timing qualifier 'before build or deploy' without unnecessary detail.

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

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

The tool is simple, has full schema coverage, has an output schema, and annotations cover its safety profile. The description supplies the essential trigger timing and expected finding categories, though explicit routing among security-related siblings would make it fully complete.

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

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

The input schema already describes both parameters with 100% coverage, so the description need not repeat them. The description adds no parameter-specific meaning, which is acceptable because the schema carries that burden.

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 names a specific action ('Check'), a specific resource ('adios.yaml'), and concrete concerns (security issues, exposed secrets, risky command patterns). This clearly separates it from writer siblings like write_workspace_adios_yaml and broader security 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?

It provides a clear usage context: 'before build or deploy.' It does not explicitly name alternatives or exclusions, such as when to prefer security_review_workspace, so the guidance is contextual but not fully prescriptive.

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 destructiveHint=true, so the description does not need to restate destructiveness. It adds useful behavioral context beyond the annotation: the action is a close-without-merge and requires explicit user approval, which clarifies the safety gate for a destructive operation.

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

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

A single sentence carries the action, key scope constraint ('open'), the critical distinction ('without merging'), and the user-approval precondition. There is 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?

For a destructive close action with output schema, annotations, and 100% schema coverage, the description is largely complete: it states the target state, the non-merging behavior, and the approval requirement. It could be slightly more explicit about the merge_pull_request alternative, but nothing essential for a correct call 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 the input schema fully documents team_id, repository_id, pull_request_id, and approved. The tool description mainly reinforces the approved parameter by mentioning explicit user approval, but it adds no meaning beyond the schema fields.

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 and resource ('Close an open pull request') and immediately distinguishes itself from merge_pull_request by adding 'without merging.' An agent can tell this tool apart from sibling tools like merge_pull_request and get_pull_request without opening 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 'without merging' implicitly routes the agent away from merge_pull_request, and 'after explicit user approval' establishes the required precondition. However, it does not explicitly name an alternative or state when merging should be chosen instead, leaving some inference to the agent.

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, so the description's 'without modifying it' reinforces rather than adds materially to the safety profile. It adds modest context about the operation being scoped to a hosted repository, but does not disclose comparison output behavior or edge cases.

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 that names the action, the object, and the non-destructive guarantee. Every word earns its place and there is no redundant filler.

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

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

Given complete parameter schema coverage, an output schema, and annotations covering safety, the description is sufficient for a simple compare operation. It could be more complete by noting that base and head should be valid branches or what kind of comparison result the caller should expect, but the schema and output schema already carry much of that burden.

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 all four parameters documented in the input schema. The description adds no parameter-specific meaning, 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 states a specific verb ('compare'), a resource ('two branches in one hosted Git repository'), and a key qualifier ('without modifying it'). This makes the tool's purpose immediately distinguishable from branch creation, listing, and workspace git 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 clearly implies when to use the tool: when an agent needs to compare two branches in a hosted repository. It also sets the scope ('hosted Git repository') and non-mutating nature, but 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?

Beyond the annotations, which already indicate this is a write operation, the description adds important behavioral detail: creating the task never executes it and requires separate user approval. This helps the agent understand the proposal workflow and avoid assuming the task is immediately actionable.

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 deliver the essential purpose and the critical approval caveat with no filler. The key behavioral constraint is front-loaded in the first sentence, making the tool's intent immediately clear.

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 is complete for a creation tool: it states what is created, the proposal nature, and the approval requirement. An output schema exists, so return value details do not need to be in the description, and the parameter schema fully covers input semantics.

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 every parameter is already documented in the input schema. The description does not add field-level meaning, but none is needed because the schema already provides concise descriptions for all seven parameters.

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 ('Save') and resource ('follow-up TODO as proposed'), and it clarifies the key semantic distinction that creating a proposed task is not the same as executing it. This clearly separates create_project_task from execution-oriented tools and from list_project_tasks.

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: use this tool when you need to save a follow-up TODO as a proposal, and it explicitly flags that the task will not be executed until a user approves it. It does not name alternatives or list when-not-to-use scenarios, but the core usage context 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?

Annotations already signal a write operation (readOnlyHint=false) with no destruction (destructiveHint=false), so the bar is lower. The description adds meaningful context beyond that: the PR is sourced from the agent work-cycle branch, and the side-effect boundary is drawn at opening the PR without merging. It does not contradict any annotation.

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 (16 words) that front-load the primary action and then add the single most important scope caveat. Every word earns its place; there is no filler or redundant restatement of the tool name.

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 an output schema present, fully documented parameters, and annotations covering the mutation profile, the description only needs to supply the source-branch scope and the non-merge boundary — both of which it does. Minor omission: nothing about the target branch or whether the branch must be pushed first, but that is not required to invoke the tool correctly.

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

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

Schema description coverage is 100% — every one of the six parameters has a descriptive entry (e.g., 'The current isolated work-cycle ID'), so the baseline of 3 applies. The description adds no parameter-level detail and does not need to, since the schema already carries that weight.

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 ('Open a pull request') and a precise scope ('from the agent work-cycle branch'). The explicit statement 'This does not merge it' distinguishes it from sibling merge_pull_request and close_pull_request, so an agent can tell the tools apart without opening either 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 'agent work-cycle branch' framing gives clear context for when this is the right step in a workflow. However, it never names the alternative for merging or states explicit when-not-to-use conditions — the distinction from merge_pull_request is implied by 'does not merge it' rather than stated as 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?

No contradiction with annotations: readOnlyHint: false correctly aligns with a create/write operation, and destructiveHint: false is consistent with branch creation. The description adds modest context via 'isolated' and 'run-scoped' but doesn't disclose failure modes (e.g., existing branch name) or whether the operation affects the workspace state.

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 11-word sentence front-loads the action ('Create an isolated branch') and scopes the resource ('in the run-scoped hosted Git repository'). Every word earns its place; there is 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?

For a simple create operation with all four required parameters fully documented, annotations present, and an output schema defined, the definition conveys what an agent needs to invoke it correctly. The only notable absence is sibling-routing guidance, which is already accounted for in usage guidelines.

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 all four parameters are already documented (e.g., 'from' = 'The existing source branch or commit.', 'repository_id' = 'The run-scoped hosted repository ID.'). The description adds no parameter-level meaning beyond the schema, hitting the baseline for high 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?

States a specific verb ('Create') and resource ('isolated branch in the run-scoped hosted Git repository'), clearly conveying what the tool does. It reads distinctly from sibling list/compare tools by the create verb, but doesn't explicitly name any sibling it is not.

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 'isolated branch' and 'run-scoped' imply the usage context — creating a run-local branch — but no explicit when-to-use or when-not-to-use guidance is given. With many git-related siblings (list_repository_branches, compare_repository_branches, workspace_git_push_branch), routing 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 establish that the operation is not read-only and not destructive, so the description does not contradict them. It adds useful context about the run-scoped repository and branch mounting, but it does not detail side effects, prerequisites, or behavior beyond creation.

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 states the action, source, and scope without wasted words. The key qualifier ('from one branch') is front-loaded, making the description easy to parse.

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 complete parameter descriptions, an output schema, and annotations, the essential call information is present. However, the description does not clarify when to choose this tool over the similarly named create_workspace sibling, which is a notable completeness gap for an agent selecting among tools.

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 schema already documents all four parameters. The description adds no new parameter-level meaning beyond tying the branch and repository concept together, which matches the baseline of 3.

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

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

The description uses a specific verb ('create') and resource ('workspace from one branch in the run-scoped hosted Git repository'), making the core action clear. It does not explicitly name sibling tools like create_workspace, so it stops short of full differentiation.

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

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

The wording implies the tool is for creating a workspace from a repository branch, but it gives no explicit when-to-use or when-not-to-use guidance and does not contrast with create_workspace or workspace_git_* alternatives. The usage context must be inferred.

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 this is not read-only and not destructive, so the description is consistent. The word 'shell' adds a small behavioral nuance that this creates a scaffold rather than a fully built workspace, but it does not disclose idempotency, side effects, or authorization needs.

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?

One concise sentence that front-loads the verb and object. There is no filler, redundancy, or unnecessary detail.

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

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

The schema fully documents parameters, annotations provide the read/write safety profile, and an output schema exists, so invocation basics are covered. However, the description is too vague about what 'workspace/project shell' means and does not position this tool relative to the many workspace-related siblings.

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?

All five parameters are already described in the input schema, so the description does not need to restate them. It also adds no extra meaning about how parameters like branch, repository_url, or workload_id relate to the created workspace.

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?

Describes a clear action ('Create') and a clear resource ('Adios workspace/project shell'), so the agent knows what the tool does. However, it does not differentiate it from sibling workspace-creation tools like create_repository_workspace, and the term 'shell' is slightly ambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives such as create_repository_workspace or deploy_workspace. There are no explicit conditions, prerequisites, or exclusions, so the agent must infer usage from the name alone.

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?

destructiveHint=true already flags the destructive nature, and the description aligns with it by saying "Delete." The description adds only the single-file scope and does not disclose whether deletion is permanent, whether it is gated on the 'approved' parameter, or how it interacts with git history. With annotations covering the core destructive trait, the added context is minimal but not misleading.

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 six-word sentence with the verb front-loaded and zero filler. Every word earns its place, and the scope is stated in a single readable clause.

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 schema covers all parameters and an output schema exists, so the structured data carries much of the load. However, the description omits the approval protocol hinted at by the optional 'approved' parameter, says nothing about irreversibility or recovery, and gives no pointer to safer alternatives. Adequate for basic invocation but thin for a destructive 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?

Schema description coverage is 100%, so all four parameters (path, team_id, approved, workspace_id) are already documented. The description's "file from a workspace" loosely mirrors path and workspace_id but adds no new parameter-level meaning, keeping this at the schema-covered baseline.

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: "Delete one file from a workspace." The singular 'one file' plus the delete verb implicitly separates it from siblings like read_workspace_file, move_workspace_file, and write_workspace_files, though no sibling is named explicitly.

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

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

There is no guidance on when to use this tool versus alternatives such as move_workspace_file, write_workspace_file, or the workspace_git_action siblings. No conditions, exclusions, or prerequisites are stated, so the agent must infer appropriate usage entirely from the tool name and sibling 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 indicate this is a destructive, mutating operation, and the description adds the useful regional default behavior. It does not go further to describe consequences of deployment, such as what is replaced or affected, but the annotation bar is already met.

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 compact and front-loaded: the first sentence states the core action and precondition, and the second gives a practical default. Every word earns its place with no redundancy or boilerplate.

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 a moderately complex mutation flow with an approval flag, but the schema already documents the 'approved' parameter fully. The description covers the primary action and the region default, and the output schema exists, so the agent has enough context to use the tool correctly.

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

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

Schema description coverage is 100%, so the schema carries the basic parameter definitions. The description adds genuine value for 'region' by explaining the default behavior when omitted, and it reinforces the meaning of 'build_id' by framing the deployment around an existing build.

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 ('Deploy'), a specific resource ('a workload'), and a key precondition ('using an existing build ID'). This clearly distinguishes it from siblings like deploy_workspace and build_workspace, which involve different resources or build creation.

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 makes clear that this tool is appropriate when an existing build ID is available, and it gives concrete guidance about the region parameter ('Omit region to use the team's home region'). It does not explicitly name alternatives or list exclusion conditions, but the usage context is clear enough.

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 signal destructive and non-read-only behavior, lowering the burden on the description. The description adds the region default behavior and the choice between current workspace and an existing build, but it does not disclose what deploying actually changes, what gets overwritten, or what side effects occur in the linked workload. This is acceptable but not rich.

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, and the main action is front-loaded. Every word contributes to understanding what the tool does or how to invoke it.

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 schema documents all parameters and an output schema exists, so return values are covered. However, for a destructive deploy operation in an open world, the description lacks context about approval requirements, what 'linked workload' means, what the deployment affects, and how this differs from deploy_workload. It is minimally viable 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 100%, so the baseline is 3. The description adds meaningful semantic value beyond the schema by explaining the region default ('Omit region to use the team's home region') and clarifying that a build may be provided instead of the current workspace. This goes beyond the raw 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 verb ('Deploy') and resource ('current workspace or provided build' to the 'linked workload'), making the core action clear. It does not explicitly distinguish itself from the sibling tool deploy_workload, which may overlap, so it loses the fifth point.

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 operational instructions ('Omit region to use the team's home region') but provides no guidance on when to use this tool versus alternatives such as deploy_workload or the build_workspace family. There are no exclusions, prerequisites, or conditions that would help an agent select among siblings.

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, so the read-only safety profile is covered. The description adds a useful framing via 'current persisted plan,' implying the returned plan is stored state, but it does not disclose auth requirements, rate limits, or ordering/pagination behavior. It is consistent with annotations and adds modest value beyond 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 a single, front-loaded sentence with no filler. It states the verb and resource first, then compactly enumerates the relevant data categories, making it easy for an agent to parse quickly.

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

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

Given the tool has only two fully documented parameters, explicit read-only annotations, and an output schema, the description is complete enough for correct invocation. It names all major result components, and the output schema covers return-value details, so no critical context 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 team_id and agent_session_id are already fully documented in the input schema. The description adds no extra parameter-level meaning beyond identifying the resource being fetched, 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 and resource—'Get an agent session transcript, runs, current persisted plan, plan steps, and run events'—and enumerates exactly what the tool returns. This clearly distinguishes it from sibling list tools like list_agents or list_agent_runs, which retrieve catalogs rather than a single session's detailed state.

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 makes the use case clear: call this when you need the full state of one agent session, including transcript, runs, plan, plan steps, and events. It does not explicitly name alternatives or exclusions, but the context is strong enough for an agent to choose it over list-style siblings.

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, so the safety profile is covered. The description adds that the response includes source and requested resources, but it does not disclose additional behavioral details such as error cases, permissions, or response characteristics.

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 communicates the core operation and the key included content with no wasted words. It is appropriately concise for a simple getter.

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 a full output schema, documented parameters, and safe annotations, the description is largely complete. It clearly identifies the resource type and scope, though it could be slightly more explicit about the relationship between app_id and the workload concept.

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

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

The input schema already documents both parameters with 100% coverage, so the base is 3. The description does not add meaningful parameter-level detail beyond framing the resource as a 'team workload,' which is helpful but not extensive.

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 ('Get one team workload') and identifies the resource plus what is included ('source and requested resources'). It is clearly a single-item read operation, though it does not explicitly differentiate from siblings like list_apps or get_workload_logs.

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

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

The description implies use when retrieving one specific team workload, especially since it requires both team_id and app_id. However, it gives no explicit when-to-use guidance, exclusions, or comparison to alternative 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 declare readOnlyHint=true and destructiveHint=false, so the read-only behavior is covered. The description adds the idea of 'bounded occurrences,' which hints at limiting behavior, but it is vague and does not explain whether the bounds come from the limit/since/until parameters or from the incident itself.

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 filler. It communicates the action, the target, and the lookup key efficiently without repeating schema or annotation information.

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

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

For a read-only fetch tool with full schema coverage and an output schema present, the description is adequately complete. It could have been stronger by noting team scoping or explicitly contrasting with list_observability_incidents, but it is not missing critical operational information.

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 schema already documents all parameters. The description highlights fingerprint as the key lookup mechanism, which matches the schema, but it adds no substantial meaning beyond what the parameter descriptions already provide.

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 ('Get') and resource ('one incident') with a clear retrieval key ('by fingerprint'). It clearly distinguishes itself from sibling list tools like list_observability_incidents because it targets a single incident rather than a collection.

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 should be used when the agent has a specific incident fingerprint and wants that incident plus occurrences. However, it does not explicitly state when to prefer this over list_observability_incidents or mention any exclusion criteria.

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, so the safe read-only behavior is covered. The description adds that the result includes current branch hashes, but does not describe pagination, snapshots, or any other behavioral nuance; with this low complexity, neutral is appropriate.

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

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

The description is a single front-loaded sentence with no filler. Every word contributes to specifying what the tool returns, including the distinctive 'current branch hashes' detail.

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

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

Given three simple, fully documented ID parameters, an output schema, and read-only annotations, the description provides sufficient context for correct invocation. Nothing critical is missing for this read 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?

Schema description coverage is 100%, and each of the three IDs (team_id, repository_id, pull_request_id) is already described. The description does not add parameter-level detail or clarify how the IDs relate, so it meets the baseline but does not add 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?

States a concrete operation: 'Get one pull request' and an additional specific detail, 'current branch hashes.' This distinguishes it from list_pull_requests, which handles multiple PRs, and from create/merge/close mutations.

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 singular 'one pull request' implies this is for single-PR retrieval rather than listing, but there is no explicit when-to-use guidance or mention of alternatives like list_pull_requests. The usage is inferable but not stated.

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. The description adds useful scoping context beyond annotations by specifying that the usage is 'current' and limited to the 'run-scoped hosted Git repository,' clarifying that it is not for workspace filesystem usage or historical data.

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 delivers the full purpose with no filler. The key qualifiers ('current', 'run-scoped', 'hosted Git repository') are front-loaded and all earn their 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 read-only lookup with a clear output schema, full parameter schema coverage, and safety annotations, this description provides sufficient context. The agent knows exactly what to retrieve and has the required identifiers.

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 team_id and repository_id having simple descriptions. The tool description does not add meaningful semantics beyond the schema, which is acceptable given full 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?

Description states a specific verb ('Get') and resource ('current disk usage for the run-scoped hosted Git repository'), which clearly distinguishes this tool from siblings like list_repositories or get_workspace_git_status. No ambiguity about what it 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 intended use is implied by the phrase 'current disk usage' and the run-scoped repository context, but the description does not explicitly state when to prefer this tool over alternatives or mention any exclusions. There are no closely related sibling tools, so the lack of explicit routing is acceptable but still leaves guidance implicit.

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, openWorldHint=false, destructiveHint=false, so the description doesn't need to restate safety. The description adds one behavioral fact: it returns the concrete home region used for default deployments, not a range or configuration. No contradiction with annotations. It does not disclose details like whether fallback logic or caching is involved, but the simple scope is adequately 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?

One sentence, no filler, directly front-loads the point: 'Return the concrete home region used for default deployments by a team.' 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 simple read-only single-parameter tool with full schema coverage and an output schema, the description is nearly complete. It could optionally mention what to do if a team has no default region, but that gap is minor given the output schema exists.

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 only parameter team_id has a schema description 'The ID of the team.' Schema description coverage is 100%, so the schema already explains the parameter. The description does not add format, source, or example guidance for team_id. 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?

States a specific action (return) and resource (concrete home region used for default deployments by a team). The scope is clear, but it doesn't distinguish itself from sibling tools beyond the 'get_team_deployment_context' name; however, the phrase 'concrete home region' and 'default deployments' gives enough specificity.

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 says this retrieves deployment context for a team, which implies it is for inspecting where a team deploys by default, but it does not explicitly state when to prefer it over sibling tools like get_workspace or list_workspaces. No alternatives or exclusions 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so this is clearly a safe read operation. The description adds the 'team-scoped' behavioral context, but does not describe error cases, permissions, or response specifics. With annotations covering the core safety profile, this is adequate but not rich.

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 filler. Every word adds meaning: 'one' indicates cardinality, 'team-scoped' indicates scope, and 'definition' indicates the type of object returned.

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 retrieval tool with a fully documented parameter schema and an output schema present, the description is complete enough. An agent can understand what the tool does, what identifiers are needed, and that this is a non-destructive 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?

Schema description coverage is 100% and both parameters have clear descriptions, so the schema already documents the parameters. The description adds only the 'team-scoped' framing, which clarifies team_id's role but does not add meaningful semantic detail beyond the schema.

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

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

The description uses a specific verb ('Get') with a specific resource ('one team-scoped workflow definition'), clearly indicating this returns a single workflow rather than a list. This distinguishes it from siblings like list_workflows, and the 'team-scoped' qualifier adds useful scope information.

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?

Usage is implied by the verb and resource: use this when you need one workflow definition identified by team_id and workflow_id. However, there is no explicit guidance on when to prefer alternatives like list_workflows or how to handle unknown IDs, so it relies on inference rather than direct 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered and 'Get recent logs' is consistent with those hints; no contradiction exists. The description adds a small behavioral detail — that logs are scoped to recent entries, implied also by the 'lines' parameter — but does not disclose anything richer such as output truncation or freshness 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 a single efficient sentence with the verb front-loaded and zero wasted words. It is appropriately terse, though it is on the minimal side because it omits any differentiating or usage context that would make the sentence more 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?

The output schema, 100% parameter coverage, and read-only/destructive annotations carry much of the burden, so the tool is callable from structured data alone. The key missing piece is disambiguation from at least three sibling log-retrieval tools, which is significant given how easy it would be for an agent to select the wrong log tool.

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

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

Schema description coverage is 100%, so the schema already documents team_id, workload_id, and lines adequately, warranting the baseline score of 3. The word 'recent' in the description adds only a weak semantic tie to the 'lines' parameter (number of recent lines to return) and does not materially improve parameter understanding.

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 ('Get'), a resource ('logs'), and a target ('a workload'), so an agent knows what the tool does. However, it does not differentiate from closely related siblings such as get_workspace_logs, get_workspace_command_logs, and query_observability_logs, leaving the workload-vs-workspace distinction to the tool name alone.

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

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

The description provides no guidance on when to use this tool versus the multiple other log-fetching siblings in the toolset (get_workspace_logs, get_workspace_command_logs, query_observability_logs). An agent must infer the right choice from the name and schema, with no stated prerequisites, exclusions, or alternative selection criteria.

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=true and destructiveHint=false, so the safe read-only nature is established. The description adds scoping via 'one ... by ID' but does not enrich behavioral context further, such as what fields are returned or whether the workspace must belong to the team_id. No contradiction exists.

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 filler. It states the operation, the object, and the selection key in six words, which is appropriately concise for a simple getter.

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

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

Given the tool's low complexity, complete parameter schema, output schema, and annotations, the description is sufficient for an agent to know when and how to call it. No critical details are missing for a straightforward read 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?

Schema description coverage is 100%, so the schema already documents both team_id and workspace_id. The description's 'by ID' aligns with workspace_id but adds no deeper meaning beyond what the schema provides, 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 uses a specific verb ('Get') with a specific resource ('one Adios workspace') and a clear selector ('by ID'). It is immediately distinguishable from siblings like list_workspaces and get_workspace_command_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?

The phrase 'one Adios workspace by ID' implies the correct use case: fetch a single workspace when its ID is known. However, it does not explicitly mention alternatives such as list_workspaces or when one of the other workspace-related getters would be more 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?

The annotations already signal readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description is consistent with these annotations but adds no extra behavioral context such as pagination, log scope, or response characteristics.

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 filler or redundancy. It earns its place and does not waste agent attention.

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 an output schema present, all three parameters documented, and annotations covering the read-only safety profile, the description is mostly complete for a simple lookup. The main gap is not naming the closest sibling alternatives to clarify the scope of 'workspace command' logs.

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?

Input schema coverage is 100% and each parameter has a straightforward description. The tool description itself contributes no additional parameter semantics, which is acceptable because the schema carries the full burden.

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

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

The description states a clear verb ('Get') and a specific resource ('logs for a workspace command'), so an agent knows the basic operation. However, it does not explicitly distinguish this from sibling tools like get_workspace_logs or get_workspace_command_status, and it adds little beyond unpacking the tool name.

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

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

There is no guidance about when to prefer this tool over get_workspace_logs or get_workspace_command_status, and no exclusions or prerequisites. The intended use is only weakly implied by the purpose statement.

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 profile. The description is consistent with this and adds no extra behavioral context, which is acceptable for a simple status getter.

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 with no wasted words. It communicates the core operation clearly and 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?

For a simple read-only status tool with full schema coverage and an output schema, the description is minimally adequate. However, it lacks guidance on how this relates to run_workspace_command or get_workspace_command_logs, so an agent might not know when to choose this tool.

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

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

Schema description coverage is 100%, so all three parameters are documented in the schema. The description adds no additional parameter-level meaning, which meets the baseline given the 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 clearly states the verb ('Get') and the resource ('status of a workspace command'). It is distinct enough from siblings like get_workspace_git_status, but it does not explicitly differentiate itself from related command/run 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 usage guidance is provided. The description does not say when to use this tool, when not to use it, or mention alternatives such as get_workspace_command_logs or get_workspace_run_status.

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 establish readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds no behavioral depth beyond the subject matter - it doesn't disclose whether the status reflects the local working tree, whether it involves network fetch, or when the result might be stale. No contradiction with annotations, but little added context.

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

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

A single five-word sentence, front-loaded and with zero redundancy; every word earns its place. It borders on under-specification but there is no wasted 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?

Structured context is rich: full schema coverage, an output schema, and safety annotations - so the description's burden is limited. The remaining gaps are defining the scope of 'git status' in the workspace context and routing usage against sibling tools, both of which are absent. Adequate for a simple read-only status call, but with clear holes.

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% - team_id and workspace_id both have descriptions - so the baseline of 3 applies. The description adds no parameter information 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 states a specific verb ('Get') and resource ('workspace git status'), and the 'git' qualifier distinguishes it from sibling status tools like get_workspace_command_status and get_workspace_run_status. However, it doesn't specify what the status actually contains (e.g., branch, uncommitted changes, ahead/behind) and doesn't name alternatives.

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

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

No guidance is provided on when to use this tool versus siblings such as get_workspace_command_status, get_workspace_run_status, or list_workspace_files. The description contains no conditions, exclusions, or 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'Get' is consistent with that safe read profile. The description adds minor context (runtime logs are tied to previews), but discloses no side effects, auth needs, or rate limits. With the annotations covering the safety profile, a 3 is appropriate.

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

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

Two sentences with zero filler: the first front-loads the purpose, the second delivers the routing rule. 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 read-only log-fetching tool with full parameter schema coverage and an output schema present, the description covers the critical decision (runtime vs build, when to supply build_id). The only real gap is the lack of explicit differentiation from get_workspace_command_logs, which is a minor omission 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 100%, so the baseline is 3. The description adds relational meaning beyond the schema by clarifying that build_id is used with type=build and that runtime logs correspond to previews, which helps build a mental model. This is helpful but not substantial enough to exceed the baseline for fully documented parameters.

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

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

The description states a clear verb+resource pair ('Get workspace ... logs') and narrows scope to 'runtime or build' logs, which implicitly separates it from siblings like get_workspace_command_logs and get_workload_logs. However, it does not explicitly name the sibling it is not, so the differentiation is inferred rather than stated.

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

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

The second sentence gives explicit, actionable directives: 'Use type=runtime for preview runtime logs, type=build for build logs, and build_id for a specific build.' This is clear context for choosing parameter values, but it does not address when to prefer log-related siblings such as get_workspace_command_logs or query_observability_logs, so no exclusions are given.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, which covers the safety profile. The description adds no additional behavioral context beyond the action itself, but it does not contradict the annotations. With annotation coverage present, this is acceptable but not enhanced.

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

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

The description is a single concise sentence with no filler and the action is front-loaded. It does not waste words, though the phrase 'preview runtime status' is somewhat jargon-heavy and could be clearer.

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 status tool with annotations and an output schema, this is minimally viable. However, the description does not clarify what a 'workspace preview runtime' is, how it relates to workspace runs, or when to choose this over get_workspace_command_status, leaving some contextual ambiguity.

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

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

Schema description coverage is 100%, and both team_id and workspace_id already have clear descriptions in the input schema. The description does not add any extra parameter-level meaning, so the baseline of 3 applies.

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

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

The description states a clear verb ('Get') and a specific resource ('workspace preview runtime status'), so an agent can tell this is a read-only status lookup. However, it does not explicitly distinguish itself from sibling tools like get_workspace_command_status or get_workspace_git_status, so the differentiation is left to inference.

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

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

There is no guidance about when to use this tool versus alternatives such as get_workspace_command_status, start_workspace_run, or stop_workspace_run. No context, exclusions, or sibling comparisons are provided, so the agent has to guess which status tool is appropriate for a given situation.

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 and destructiveHint, and the description adds meaningful behavioral context by stating that no SQL is executed. This tells the agent the tool is a metadata inspection operation, not a query runner. Other behaviors like auth scope are not mentioned, but the annotations plus description cover the key 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 a single dense sentence with no filler. The core action, scope, and behavioral boundary are all front-loaded, and every phrase 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 read-only, 3-parameter inspection tool with 100% schema description coverage and an output schema present, the description is complete. It supplies the critical non-SQL guarantee, while invocation details are already in the schema and annotations.

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 schema already documents team_id, workload_id, and optional database. The description does not add parameter-level detail beyond identifying the workload scope, which keeps this at the baseline 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 ('Inspect') and resource ('databases and tables') tied to a single database workload, which clearly distinguishes this tool from log, workspace, and repository tools in the sibling list. The phrase 'without executing SQL' adds a precise boundary that prevents confusion with any querying tool.

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: use this when inspecting database or table metadata for a specific workload, and it explicitly rules out SQL execution. It does not name a direct alternative or list when-not-to-use cases, but no sibling appears to serve the same exact purpose, so the guidance is strong enough.

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 readOnly=false and destructive=true, so the safety profile is covered. The description adds valuable non-obvious behavior: the command is queued, not run synchronously, and progress is observed via two named sibling tools.

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, with the primary action and return value front-loaded in the first sentence and the follow-up polling instructions in the second.

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 2-parameter queueing tool with output schema and annotations, the description tells the agent what to do after invocation (poll status/logs). It doesn't detail potential side effects, but the destructiveHint annotation covers that and the description is otherwise sufficient.

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?

Input schema covers both parameters with 100% coverage, so the baseline is 3. The description adds no parameter-specific meaning beyond identifying the target workspace linguistically, which is acceptable because the schema already documents them.

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 ('Queue'), names the exact resource ('canonical workspace lint command'), and states the return value ('command_id'). It clearly distinguishes this from sibling run/start/build tools by framing it as an asynchronous queued lint operation.

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 explains the expected flow: call this to queue lint, then poll get_workspace_command_status and get_workspace_command_logs. It doesn't explicitly state when to prefer alternatives, but the canonical lint scope and polling direction provide clear context.

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, so safety is covered. The description adds 'durable' (persistent history) and 'bounded' (limited results), which are useful behavioral hints, but it does not disclose ordering, default limit, 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, front-loaded sentence with no filler. It communicates the core purpose and key constraint 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 output schema, full parameter documentation, and annotations, the description is adequate for a read-only list tool. However, it does not clarify what an 'agent run' is relative to the sibling 'workflow run' concepts, which could cause selection ambiguity in a rich sibling 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 description coverage is 100%, so the schema already documents every parameter. The description only vaguely references 'bounded team-scoped filters' and adds no parameter-specific meaning beyond that.

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

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

The description states a specific verb ('List'), a clear resource ('durable agent run history'), and a scoping qualifier ('bounded team-scoped filters'). This distinguishes it from sibling list tools like list_workflow_runs and list_workspaces.

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 for retrieving agent run history, but it does not explicitly state when to prefer it over alternatives such as list_workflow_runs or get_agent_state. No exclusions or alternative conditions are provided.

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

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

Annotations already declare the tool read-only and non-destructive. The description adds useful behavioral context beyond those annotations: results are scoped to what is authorized for a team, and it enumerates the categories returned (definitions, versions, suites, bindings). 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, dense sentence that front-loads the action and resource, then lists the scope and entity types. Every phrase contributes meaning, with no filler 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 one-parameter, read-only list operation with an output schema and safety annotations, the description is complete enough. It specifies the entity types and team scoping, while the output schema covers return structure.

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 team_id already documented as 'The ID of the team.' The description's 'for a team' phrase aligns with the parameter but adds no additional semantic detail beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('List') with a clear resource ('agent definitions, versions, suites, and bindings') and a scoping qualifier ('authorized for a team'). This clearly distinguishes it from sibling tools like list_agent_runs, which concern runs rather than definitions or catalog entities.

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: call this when you need the agent catalog items authorized for a particular team. It does not explicitly name alternatives or exclusions, but the resource scope is specific enough that an agent can infer when it applies.

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 profile. The description adds context about the included resource categories (apps, APIs, workers, databases, caches), which is useful but does not disclose pagination behavior, default limits, or ordering. This is adequate but not rich behavioral detail.

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

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

The description is a single focused sentence with no wasted words. The primary action and resource scope are front-loaded, and the example categories add value without bloating the text.

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 output schema exists and all parameters are documented, the description is nearly sufficient for calling the tool. However, the lack of usage guidance relative to numerous sibling tools and the absence of any note about pagination or filtering behavior leave some gaps for an agent navigating a large toolset.

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 every parameter is documented in the schema. The description's list of workload categories adds mild context for the 'type' filter, but it mostly reinforces what the schema already says. Baseline 3 is appropriate when the schema carries the parameter documentation burden.

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

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

The description states a clear verb-resource pair ('List team workloads') and enumerates the included workload types, which helps an agent understand scope. It does not explicitly contrast with sibling tools like list_workspaces or get_app, so it stops short of full differentiation.

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

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

No guidance is given about when to use this tool versus alternatives such as list_workspaces, list_agents, or deploy_workload. The description only implies that listing workloads is the purpose, leaving the agent to infer when this tool is the right choice among many siblings.

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, so the safety profile is covered. The description adds useful behavioral context by mentioning 'grouped' incidents and 'trends', signaling aggregation rather than raw incident listing, but it does not disclose details like pagination, sorting, or how grouping/trend analysis is computed.

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 filler words. It efficiently conveys the core purpose, though it could have been slightly more precise by using 'list' instead of 'analyze' and could have named the grouping behavior more explicitly.

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 presence of a full input schema, an output schema, and annotations declaring read-only and non-destructive behavior, the description is mostly complete for a list-style tool. It lacks explicit sibling differentiation and some behavioral details, but the structured fields compensate for those gaps.

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

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

Schema description coverage is 100%, so every parameter already has its own explanation. The tool description adds no additional parameter meaning beyond the schema, which matches the baseline of 3.

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

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

The description names a specific resource ('grouped workload incidents and trends') and a scope ('for a team'), which distinguishes it from the singular sibling get_observability_incident. However, the verb 'Analyze' is broader and less precise than 'list', so it does not fully match the tool's name and could slightly blur the tool's core listing 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?

The description implies the tool is used to examine grouped incidents and trends for a team, providing clear context. It does not explicitly state when to prefer this tool over alternatives such as get_observability_incident or query_observability_logs, nor does it mention exclusions or prerequisites.

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, so the safety profile is covered. The description adds useful behavioral context by specifying that only 'proposed and approved' durable TODOs are returned, going 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?

A single, front-loaded sentence with no wasted words. It immediately states the action, resource, and scope, making it easy for an agent to parse.

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

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

Given the simple read-only nature, the safety annotations, and the presence of an output schema, the description is largely complete. It could be slightly clearer about whether the 'proposed and approved' phrasing represents a fixed filter or the status parameter values.

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 parameters are already documented. The description adds semantic value by clarifying the task statuses included ('proposed and approved') and the 'run-scoped' nature of the project, which helps interpret the company_project_id parameter.

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

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

The description uses a specific verb ('List') with a clear resource ('durable proposed and approved TODOs') and scope ('run-scoped Company Project'). This clearly distinguishes it from siblings like create_project_task and other workspace listing 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 implies when to use the tool: when listing durable project tasks. However, it does not explicitly mention alternatives, exclusions, or conditions under which another tool should be used instead, such as create_project_task.

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, so the description needs only to add context. It confirms a read-only listing operation and clarifies that it applies to one hosted repository, but it does not describe additional behaviors like default status filtering, sorting, or pagination. The description aligns with the annotations 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?

A single, tightly worded sentence that conveys the operation, resource, and scope without extraneous detail. It is front-loaded and every word contributes to the meaning.

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, full schema coverage, and the presence of an output schema, the description is sufficiently complete for an agent to select and invoke the tool. Minor gaps such as not specifying allowed status values or pagination behavior are acceptable because the schema and output schema fill most practical 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?

Schema description coverage is 100%, so the schema already documents all parameters. The description adds the context that the repository is 'hosted' and that the call is scoped to one repository, but it does not explain parameter semantics beyond what the schema provides. This matches the baseline for full 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 verb ('List') and a clear resource ('pull requests for one hosted Git repository'), distinguishing it from singular operations like get_pull_request and from broader repository listing tools. The scoping to a single repository makes the tool's purpose immediately 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 implies the tool is for listing pull requests within a specific repository, but it does not explicitly state when to prefer it over get_pull_request, list_repositories, or other related tools. No exclusions or alternative routing guidance is provided, so an agent must infer usage from the name and schema.

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, so the safety profile is covered. The description adds that results are scoped to repositories visible to the current user in a team, which supplements the schema, though pagination or ordering behavior is not disclosed.

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

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

A single, front-loaded sentence contains the verb, object, and scope with no 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 low-complexity, one-parameter read-only list tool with an output schema and clear annotations, the description covers what an agent needs to select it. It is not exhaustive about pagination or membership semantics, but those gaps are minor given the structured 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%, and the team_id parameter is already described as 'The ID of the team.' The description adds the notion of current-user visibility but not additional parameter-specific semantics, so it meets the baseline without exceeding it.

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'), resource ('hosted Git repositories'), and scope ('visible to the current user in a team'). This clearly separates it from sibling tools like list_repository_branches or list_pull_requests, 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 for when to choose this tool over alternatives or when not to use it. The phrase 'visible to the current user in a team' is the only contextual hint, but it does not explain use cases, exclusions, or relationships to sibling list 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 declare readOnlyHint=true and destructiveHint=false, so the read-only safety profile is covered. The description adds little behavioral context beyond restating the listing action; it does not mention pagination, sorting, limits, or other runtime behavior. With the annotations in place, this is acceptable but not exemplary.

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 concise, front-loaded with the action, and contains no filler or redundant information. 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 simple list operation with two fully documented parameters, an output schema, and read-only annotations, the description is complete. It does not need to explain return values because the output schema exists, and the required identification context (team and repository) is covered by the input schema.

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

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

Schema description coverage is 100%, so both team_id and repository_id are already documented in the input schema. The description does not add any additional parameter semantics, but it does not need to since the schema fully explains each parameter's purpose.

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: 'List branches for one hosted Git repository.' It clearly distinguishes itself from sibling tools like list_repositories (which lists repositories) and create_repository_branch/compare_repository_branches (which create or compare branches). The scope is precise and unambiguous.

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

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

The description implies the tool should be used when an agent needs to list branches for a specific hosted Git repository, given the required team_id and repository_id. However, it does not explicitly mention when to prefer this tool over alternatives like compare_repository_branches or create_repository_branch, nor does it state any exclusions or prerequisites.

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, so the safety profile is known. The description adds useful nuance by specifying 'durable runs,' which distinguishes this listing from ephemeral or non-durable execution statuses, and by emphasizing the team-scoped workflow constraint.

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 seven-word sentence states exactly what the tool does with no filler. The verb and resource are front-loaded, and 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 two required simple parameters, a full input schema, an output schema, and annotations covering the safety profile, the description is complete for an agent to invoke this tool correctly. No return-value documentation is needed because an output schema exists.

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 team_id and workflow_id both documented. The description's 'team-scoped workflow' hint adds a small relational nuance, but the schema already carries the parameter meaning, so the description does not need to compensate.

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 ('List') with a clear resource ('durable runs') and a precise scope ('one team-scoped workflow'). It is clearly distinguishable from siblings like list_workflows, which list workflow definitions, and start_workspace_run, which initiates runs.

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 'for one team-scoped workflow' gives clear context that this tool is for a single workflow within a team, requiring both team_id and workflow_id. It does not explicitly name alternatives or state when not to use it, but the scoping language makes the intended use 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 declare readOnlyHint=true and destructiveHint=false. The description adds the visibility-scoped behavior ('visible to a team'), clarifying that the returned list is filtered by team visibility rather than being a global listing. This adds meaningful behavioral context 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?

A single sentence with no filler or redundancy. The essential scoping information is front-loaded and every word carries meaning.

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 full schema parameter descriptions, an output schema, and annotations covering safety, the description is complete. The only non-obvious contextual detail—team-scoped visibility—is explicitly stated.

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 value by clarifying that team_id refers to the team whose visible workflows are listed, strengthening the meaning of the required parameter. It also implies limit/offset/status are standard pagination and filtering controls, consistent with the schema.

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

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

The description uses a specific verb ('list') and resource ('workflows'), and adds a scoping qualifier ('visible to a team') that makes the resource distinct from siblings like list_workflow_runs. This clearly identifies what the tool does and its target resource.

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

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

The description implies the tool should be used when workflows visible to a team are needed, but it does not explicitly contrast with alternatives such as list_workflow_runs or discuss when not to use it. Some usage context is present, but no explicit exclusions or 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?

Annotations declare readOnlyHint=true and destructiveHint=false, so the safety profile is already known. The description adds behavioral context by specifying the tool traverses the complete visible workspace tree and includes dot-directories, which is not obvious from annotations or the schema. It also highlights the path '.' behavior, adding operational detail beyond 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 sentences with no filler. The first sentence states the core purpose, and the second provides a concrete usage tip. Every word contributes to either understanding or efficient invocation, and the most important information is front-loaded.

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

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

For a listing tool with read-only annotations and an output schema, the description covers the essential usage and scope. It explains what is listed, includes dot-directories, and gives a practical path example. Minor missing context includes potential permission requirements or whether the tree is recursive, but these are partially addressed by the output schema and annotations.

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 schema already documents all three parameters. The description redundantly mentions the '.' path convention that is also in the schema's path description, without adding new parameter semantics. Baseline 3 is appropriate since the schema handles parameter documentation adequately.

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: 'List the complete visible workspace tree', with the specific differentiator that it includes project dot-directories such as .adios. This distinguishes it from sibling tools like list_workspaces (lists workspaces) and read_workspace_file (reads file 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 gives explicit usage guidance: 'Use path '.' to inspect the repository root before answering from connected project context.' This tells the agent when and how to invoke the tool effectively. It does not explicitly name alternative tools for different scenarios, but the context is clear enough for an agent to decide.

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, so the description does not need to restate that. It adds no behavioral context beyond what the schema indicates, such as pagination behavior, status filter semantics, or whether the result is limited to active workspaces.

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 filler. It communicates the core purpose efficiently and avoids redundant restatement of the tool name.

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 listing tool, the description combined with a fully documented schema and existing output schema is reasonably complete. The main gap is the lack of usage guidance around sibling list tools, but the essential invocation requirements are 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 100%, so the input schema fully documents team_id, limit, offset, and status. The description mentions team scoping but adds no parameter-level detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific action and resource: 'List Adios workspaces for a team.' It is clear that this tool retrieves workspace records scoped to a team. It does not explicitly call out how it differs from sibling tools like get_workspace or list_workspace_files, so it stops short of full differentiation.

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

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

The description gives no guidance on when to use this tool versus alternatives such as get_workspace, list_workspace_files, or create_workspace. There are no conditions, exclusions, or references to sibling tools. The context must be inferred entirely from the tool name and description.

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, lowering the description's burden. The description adds a meaningful guardrail — that explicit user approval is required before merging. It does not disclose post-merge consequences such as the PR being closed or the target branch receiving permanent changes, which would add real 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?

A single sentence with no wasted words: verb first, then the resource, then the approval precondition. It is appropriately sized given that the schema and annotations carry the detailed information.

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

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

With an output schema present and annotations covering the destructive nature, the description is adequate for a straightforward mutation. It omits what happens after a successful merge — PR closes, changes become permanent on the base branch — and doesn't address failure states like merge conflicts, which would make it 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 all four parameters are already documented in the schema, giving a baseline of 3. The description's emphasis on 'explicit user approval' reinforces the `approved` parameter's role but adds little beyond what the schema's 'Must be true after explicit user approval' already states.

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 ('Merge') and resource ('open pull request'), which makes the operation clear and distinct from siblings like create_pull_request or list_pull_requests. The precondition 'after explicit user approval' adds precision, but it doesn't explicitly differentiate from close_pull_request, which is the closest sibling in behavior.

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 'after explicit user approval' implies the key gate for invoking this tool, and 'open pull request' implies it should not be called on closed or non-existent PRs. However, no alternatives are named and there is no explicit when-not-to-use guidance beyond the approval requirement.

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 declare a non-read-only, destructive operation (readOnlyHint=false, destructiveHint=true), and the description does not contradict that. However, the description adds no extra details about side effects, such as whether an existing file at the 'to' path is overwritten or whether the source file is removed. Given that annotations already cover the destructive nature, this is a moderate gap.

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

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

The description is a single concise sentence with no filler. It is front-loaded with the action verb 'Move or rename' and immediately identifies the resource. 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 fully described required parameters, an output schema, and a destructiveHint annotation, the definition is nearly complete for invoking the tool correctly. The main missing piece is explicit collision/overwrite behavior and usage preconditions, but those are minor given the annotations and schema richness.

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%: 'from' is the current file path, 'to' is the new file path, and team_id and workspace_id are described. The description itself adds no additional parameter-level meaning. The high schema coverage supports the baseline score of 3.

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

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

The description clearly states a specific verb and resource: 'Move or rename a file in a workspace.' This distinguishes it from sibling file tools like delete_workspace_file, write_workspace_file, and read_workspace_file. The scope is unambiguous and aligns with the tool name.

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

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

There is no guidance on when to use this tool versus alternatives, such as using write_workspace_file plus delete_workspace_file to achieve the same effect. No preconditions, exclusions, or when-not-to-use situations are mentioned. The only signal is the verb itself, which is not enough to earn a higher score.

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 openly lists side-effectful behaviors: create/update, write files, generate adios.yaml, normalize dependencies, run build/start pipeline, and wait. This goes beyond the annotations and aligns with destructiveHint=true and readOnlyHint=false. It does not fully disclose risks like whether package.json is overwritten or whether an existing workspace is reset, but the annotations already signal 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 a single dense sentence that progresses logically from workspace creation through file writing, configuration generation, dependency normalization, build/start, and preview URL waiting. Every phrase contributes a meaningful step, though the run-on structure could be slightly easier to parse if broken into separate clauses.

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 overall flow and end state, the output schema handles return values, and annotations signal destructive/open-world behavior. However, for a complex composite tool it leaves important gaps: the meaning of 'canonical build/start pipeline' is vague, timeout or failure behavior while waiting for the URL is unspecified, and the exact side effects of 'normalize Node preview build dependencies' are not explained.

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

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

Schema description coverage is 100%, and the schema already documents each parameter, including the deprecated build_before_run behavior and the optional files array. The description adds no parameter-specific semantics, but it does not need to because the schema fully carries that weight.

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 composite purpose: create or update a workspace, write files, generate adios.yaml when missing, normalize dependencies, run the canonical pipeline, and wait for a preview URL. This is a specific verb+resource description with an end state that distinguishes it from sibling primitive tools like create_workspace, write_workspace_files, or build_workspace.

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 a workspace preview needs to be fully prepared end-to-end. However, it never explicitly contrasts it with the many sibling tools, such as create_workspace, write_workspace_file, or start_workspace_run, nor does it state when NOT to use this composite in favor of those primitives.

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, so the description is not responsible for that baseline. It adds a little context by noting the logs are 'bounded' and queried via the 'platform observability index,' but it does not explain what 'bounded' means in terms of limits, pagination, or scope. 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 with no filler. It immediately conveys the action, resource, and data source, making it 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?

While the schema and output schema are rich, the description is too thin for a tool with nine parameters and many closely related siblings. It lacks guidance on when to use it over get_workload_logs or get_workspace_logs, and it does not clarify the meaning of 'bounded' or the behavioral implications of querying the observability index.

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 input schema fully documents all nine parameters. The description adds no parameter-specific meaning beyond referring to 'bounded team workload logs,' which only weakly relates to filters like team_id, app_id, since, and until. 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 states a specific action ('Query') and resource ('bounded team workload logs'), and mentions the underlying platform observability index. It is clear what the tool does, though it does not explicitly differentiate it from sibling tools like get_workload_logs or get_workspace_logs.

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

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

The description gives no guidance on when to use this tool versus the many similar sibling tools such as get_workload_logs, get_workspace_logs, or list_observability_incidents. It implies relevance to team workload logs but provides no contextual selection criteria or exclusions.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: files are UTF-8 encoded, only a single file is read, and sensitive workspace paths remain denied regardless of access.

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 filler. The core action and prerequisite are front-loaded, and the sensitive-path limitation is stated in a second short sentence that 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 read tool with full schema coverage, an output schema, and annotations covering safety, the description is complete. It gives the prerequisite, the file type, and a known access limitation — everything an agent needs to 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%, so parameters are already self-documenting. The description adds a useful constraint that path must be exact and discovered via list_workspace_files, but this mostly reinforces the schema's 'exact repository-relative file path' wording rather than introducing new semantic detail.

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 ('Read one UTF-8 project file') and a clear resource, distinguishing it from write/delete siblings. The naming of list_workspace_files as the path-discovery prerequisite further differentiates this read operation from workspace listing 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?

Explicitly instructs to discover the exact path with list_workspace_files before reading, which provides clear sequencing. It stops short of listing explicit when-not-to-use alternatives, but the guidance is sufficient for an agent to know the intended call pattern.

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 this is a non-read-only but non-destructive operation. The description adds useful behavioral context: the canonical URL is immutable, aliases are globally unique, and the slug format is restricted. This goes beyond what annotations alone provide, though it does not address conflict or failure behavior.

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

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

The description is two focused sentences. It front-loads the primary purpose and immediately adds the most important constraint, with no filler 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 rename operation with fully documented parameters, annotations, and an output schema, the description is complete. It covers the operation's effect, what remains unchanged, and the key constraints an agent needs to know before calling 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 description coverage is 100%, so the parameters are already documented. The description adds extra meaning for the 'slug' parameter by specifying global uniqueness and format rules, but it does not add further semantics for team_id or workspace_id, which is acceptable given the schema already explains them.

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 names a specific operation ('Set or rename'), a specific resource ('workspace preview's friendly alias'), and a key constraint (canonical URL is immutable). This clearly distinguishes it from sibling tools like prepare_workspace_preview.

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 implicitly conveys when to use the tool: to assign or change a friendly preview alias. However, it does not explicitly state when not to use it or mention alternatives such as prepare_workspace_preview, so the 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 mark this as destructive and not read-only; the description adds async behavior (queuing rather than blocking), the command_id return, the multi-minute time frame, and the exact polling endpoints. It does not contradict annotations. It could go further by stating what happens to the currently running workspace, but the destructiveHint plus 'restart' largely cover 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?

Two sentences, zero filler. The action and return value are front-loaded; the timing and polling guidance follow in the second sentence. 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 two-string-parameter async queue tool with an output schema and safety annotations, the description covers what, return, duration, and next steps. Minor omissions — prerequisites (workspace must exist and have a runtime) and explicit contrast with start/stop siblings — keep it from a 5.

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 team_id and workspace_id are already documented in the schema; the description adds little beyond implying workspace_id refers to a preview workspace. Per the baseline rule, 3 is appropriate when the schema does the heavy lifting.

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

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

The first sentence states a specific verb ('Queue') and resource ('workspace preview runtime restast') and discloses the return value (command_id). This distinguishes it from siblings start_workspace_run, stop_workspace_run, and run_workspace_command by making the restart-and-return-command_id contract explicit, so an agent can tell them apart 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 tells the agent what to do after calling: poll get_workspace_command_status and get_workspace_command_logs for progress, and sets the expectation that builds/readiness take several minutes. This is clear usage context, though it does not explicitly state when to choose restart over start_workspace_run or stop_workspace_run.

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 communicate that this is not read-only and may be destructive. The description adds useful behavioral context: it queues the command asynchronously, returns a command_id, and requires status/log polling. No contradiction with the annotations exists.

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 tight sentences front-load the action, give concrete command examples, and cover the return contract and polling workflow. There is no filler or redundant restatement of the tool name.

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 is complete enough for an agent to invoke the tool: it explains the queueing behavior, the return value, and how to monitor progress, while the output schema can carry the exact response details. The main missing piece is guidance on sibling-tool selection, but that is more of a usage-routing concern than an invocation-completeness 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 100%, so all three parameters are already documented in the input schema. The description reiterates the command kinds but adds no new parameter-level meaning, constraints, or format details 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 clear action ('Queue'), a clear resource ('a workspace command'), and enumerates the command kinds. It also names the return value, so an agent understands what the tool does. It loses the fifth point because it does not distinguish this generic queue from specialized sibling tools like build_workspace or lint_workspace.

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 'such as test, lint, build, start, stop, or restart' implies the intended scenarios, and the polling note suggests it is for long-running commands. However, the description never tells an agent when to prefer this tool over the numerous specialized sibling commands that overlap with these kinds, leaving routing ambiguous.

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