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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so safety is covered. The description adds real behavioral context beyond that: what it scans (action-chain JS, Actions.callRest), what it compares (key sets, not values), and what it flags (keys some apps send that others omit). It doesn't describe output shape, but that gap is minor against the annotation coverage.

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

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

Three dense sentences, front-loaded with the core operation before the comparison mechanism and the use case. Each sentence carries distinct information – no restatement of the name or title.

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 audit tool with full schema coverage and no output schema, the description conveys enough: what it scans, what it compares, and the intended diagnostic. Only the practical result format (e.g. per-endpoint diff grouping) is left implicit, which is acceptable given no 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 coverage is 100%, so all four parameters are already documented in the schema, which sets the baseline at 3. The description reinforces app/endpoint filtering through its phrasing ('each app', 'cross-app', 'per endpoint') but adds no syntax or format detail beyond what the schema already gives.

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?

Specific verb+resource+scope: 'Cross-app audit of REST service usage' that 'finds every Actions.callRest call in the repo's action-chain JS' and compares parameter keys per endpoint. It explicitly draws the boundary ('Compares key sets, not values'), which distinguishes it from sibling audit tooling like run_audit.

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

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

Gives a concrete use case: 'Use it to check a shared service connection is mapped consistently across apps.' That states when to reach for it, but it never names an alternative (e.g. run_audit) or an exclusion, so it stops short of full when/when-not 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 readOnly/idempotent/non-destructive, but the description adds real value beyond them: it reports 'what's missing and the exact fix' and commits to 'never prints secrets', which is a meaningful safety guarantee. It also clarifies that live=true triggers a real network call rather than a static check.

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

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

Three compact sentences, front-loaded with scope, followed by output/safety promise and the usage trigger. Every clause carries information and nothing is padded.

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

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

With no output schema, the description still tells the agent what comes back (missing items plus exact fixes) and what the optional flag does. Safety, scope, and invocation conditions are all covered for a zero-required-parameter diagnostic tool.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema (including the repo path resolution rules and the list_repos pointer). The description only adds the nuance that live=true tests the standalone-VBCS login, which is a marginal refinement over the schema wording; 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 verb 'Diagnose' plus the object 'this install' is specific, and the description enumerates exactly what is checked (Node/git, workspace + repos, git credentials, build tools, Component Exchange URL, optional services). No sibling tool does environment diagnosis, so it is easily distinguished from git_* and vbcs_* 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?

'Run this first when something doesn't work' gives an explicit trigger condition, and 'Set live=true to also test the standalone-VBCS login' conditions the optional mode. It does not state exclusions or contrast with alternatives such as run_audit or git_status, so it stops short of a 5.

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

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

Annotations already declare readOnly=false, openWorld=true, destructive=false. The description adds real value by disclosing the write target (VBS_WORKSPACE_DIR), its downstream effect (discoverable by list_repos), and auth guidance (VBSTUDIO_GIT_USERNAME/TOKEN instead of embedding credentials in remoteUrl). This goes beyond the safety profile annotations provide.

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

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

Three tight sentences, front-loaded with the action, then context, then the credential caveat. 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?

With no output schema needed and annotations covering the safety profile, the description supplies the essential remaining context: destination behavior and credential handling. It does not cover edge cases like failure modes or behavior on an existing destination folder, a minor gap.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds meaning by warning against embedding credentials in remoteUrl and indicating the accepted auth mechanism. That is semantic guidance the schema does not supply.

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 and resource (clone a git remote) plus the destination behavior (into VBS_WORKSPACE_DIR so it's discoverable by list_repos). An agent can distinguish this from git_pull/git_status/git_commit siblings without opening a 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?

Gives implied context ('Used by /link's VBS setup flow') and a clear credential directive, but never states when to prefer this over siblings like git_pull or explains prerequisites/ordering. Usage is implied rather than differentiated from alternatives.

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=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds the useful fact that it both stages and commits in one step, but says nothing about author identity requirements, amend/force behavior, branch targeting, or whether the commit stays local until git_push.

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 eight-word sentence with the action front-loaded and zero filler. Every word carries meaning and nothing is padded.

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 non-destructive write with annotations already covering the safety profile and no output schema, the definition is minimally adequate. The remaining gaps are the relationship to git_push and whether the commit is local-only, which an agent invoking this tool would reasonably want to know.

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

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

Schema coverage is 67%: repo and files are well documented in the schema (including the important 'omit files to stage all changes' default), while message is undocumented but self-evident as the commit message. The description contributes no parameter detail at all, so the schema is doing all the work and a 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 the specific verb pair (stage and commit) and the resource (changes in a repo checkout), which is more precise than a bare 'commit' because it discloses that staging is included. It is distinguishable from git_push/git_status/git_pull by action, but it never names or contrasts those siblings, so it falls short of a 5.

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 prefer this tool over git_push (whether committing alone publishes anything) or git_status (previewing changes before committing). The implicit 'stage and commit in one call' behavior is the only usage cue, and no exclusions or prerequisites are 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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds real context beyond them: it authenticates via VBSTUDIO_GIT_USERNAME/TOKEN and will not block on a hidden credential prompt. It does not say how merge conflicts or failures are surfaced, which keeps it short of a 5.

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, with the core action front-loaded and the authentication caveat immediately after. No filler, though the phrase 'never hangs on a hidden prompt' is slightly awkward.

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 no-parameter-required, no-output-schema mutation tool, the description covers auth and non-blocking behavior but omits what happens on conflict, whether it merges or rebases, and the meaning of the branch/remote arguments. Adequate but with clear gaps.

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

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

Schema coverage is only 33% - just 'repo' is documented - and 'branch' and 'remote' are explained nowhere, neither in the schema nor in the description. With low coverage the description is expected to compensate, and it adds nothing about the 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?

States a specific verb and resource ('Pull from the repo's remote'), which cleanly separates it from git_push, git_clone, and git_status. It does not explicitly name a sibling or scope, but the operation is unambiguous.

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

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

There is no guidance on when to use this versus git_clone (initial checkout) or git_push, and no mention of prerequisites such as being on a branch or having a clean tree. The agent is left to infer the context entirely.

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 this as a non-read-only, open-world, non-destructive write. The description adds genuinely useful context beyond them: credential sourcing from VBSTUDIO_GIT_USERNAME/TOKEN and a guarantee that it never hangs on a hidden prompt. It omits whether force-push is possible or what happens on rejection/non-fast-forward.

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 compact sentences with the core action first and the operational caveat second. Every clause carries information; nothing is padding.

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 mutation tool with no output schema and two undocumented parameters, the description covers the auth and hang behaviors well but leaves branch/remote semantics and failure modes unspecified. It is adequate but incomplete for the schema's gaps.

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

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

Schema coverage is only 33% – repo is documented in the schema, but branch and remote are bare with no description anywhere. The description adds nothing about branch or remote semantics (e.g. defaults, whether remote defaults to origin), so it fails to compensate for the coverage gap.

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 and resource ("Push to the repo's remote"), which an agent can distinguish from git_commit, git_pull, and git_clone. However, it does not explicitly contrast itself with those siblings or clarify its position in the git workflow.

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 on when to push versus committing or pulling first, no prerequisites (e.g. whether a commit must exist), and no mention of alternatives. The agent must infer the workflow position 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?

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered without the description. The description adds nothing beyond that – no note on whether it touches the network, requires a git install, or how it behaves on a dirty/clean tree – but the annotation bar is 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?

One short sentence, front-loaded with the verb and resource and free of filler. It is efficient, though arguably so terse that it omits useful context.

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, zero-required-parameter tool whose only parameter is fully described in the schema and whose safety profile is fully covered by annotations, the description is sufficient to invoke correctly. The missing usage/routing guidance is a separate gap rather than a completeness failure.

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 single 'repo' parameter is documented in detail (absolute path, name under VBS_WORKSPACE_DIR, VBCS_REPO_PATH default, list_repos pointer). The description adds no parameter meaning, 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 names a specific verb ('Show') and resource ('git status') scoped to 'a repo checkout', so the agent immediately knows what the tool returns. It does not, however, distinguish itself from the git_commit/git_pull/git_push siblings beyond the obvious command 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 statement of when to use this tool, when not to, or how it relates to alternatives such as git_commit or list_repos. Usage (e.g. inspecting the working tree before committing) must be inferred entirely from the command name.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context that this reads a local repo checkout rather than a live service, but says nothing about permissions, cost, or behavior when the repo path is invalid.

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 tight sentence with the resource, scope, and on-disk naming convention front-loaded. Nothing is wasted and nothing needs to move earlier.

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

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

For a one-parameter read-only tool with full schema coverage and annotations covering safety, the description is nearly sufficient. The remaining gap is sibling disambiguation against vbcs_list_applications and what the returned names are relative to.

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 single repo parameter is fully documented with fallback semantics and a pointer to list_repos. The description adds no parameter meaning beyond that, 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?

States a specific verb and resource ("List VBCS web app names") and even gives the on-disk shape (webApps/<name>), so the output is concrete. It does not, however, distinguish itself from the sibling vbcs_list_applications, which an agent could easily confuse for this.

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 when-to-use guidance, no prerequisites, and no exclusions. The one piece of routing advice (use list_repos to see available repos) lives in the parameter schema, not the description, and the ambiguity versus vbcs_list_applications is left entirely unresolved.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds meaningful behavior beyond that: results are file names only, not contents, which tells the agent what the return set looks like. It stops short of describing path format or recursion/ordering 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?

Two tight sentences: capability and routing first, exclusion second. No filler, every sentence earns its place.

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

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

For a simple two-param read tool with annotations covering safety and no output schema, the description supplies what's needed: scope, glob semantics, and the returned granularity. A brief note on output path format or default ordering would close the remaining 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 coverage is 50% — the repo param is documented in the schema (including a pointer to list_repos), while pattern has no schema description. The description compensates with a concrete glob example that clarifies pattern syntax and path shape, which is real added 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 specific verb (list) and resource (artifact files in a repo) with scope (matching a glob pattern) plus a concrete example. It explicitly distinguishes itself from search_artifacts, so an agent can pick it 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?

Names the alternative (search_artifacts) and the exact condition that selects it: pattern-based filename listing vs. content search. The 'file names only' framing makes the boundary 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, idempotentHint=true, and destructiveHint=false. The description adds that listing is scoped to local checkouts under VBS_WORKSPACE_DIR, which is useful context beyond the annotations, though it omits return format or pagination details.

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

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

A single front-loaded sentence with zero wasted words. The scope constraint is placed clearly after the purpose.

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

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

For a zero-parameter, read-only list tool with no output schema, the description gives sufficient purpose and location scope. It could be slightly richer about the return format, but that is not essential here.

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?

No parameters exist, so the baseline score is 4. The description does not need to add parameter meaning and correctly does not attempt to.

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 ('List') and resource ('local VB Studio project repo checkouts') with scope ('under VBS_WORKSPACE_DIR'). Clear, but does not differentiate from sibling list tools like list_apps or list_artifacts.

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

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

Gives no when-to-use guidance, no prerequisites, and no alternatives. Usage is only implied by the verb, which is insufficient for routing among the many sibling list and git 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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the artifact-type scope; it says nothing about behavior on a missing/invalid path, whether binary or large files are handled, or what form the content comes back in.

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; the verb, resource, and lookup key come first. It loses a point only for the vague 'etc' tail, which adds ambiguity rather than 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?

This is a simple two-parameter read tool whose annotations cover safety and whose schema is fully documented, so little is missing. However, since there is no output schema, the description should say what is returned (raw file text? parsed structure?) and how a missing path is reported; that gap leaves the definition adequate but not 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%, with both 'path' and 'repo' documented in the schema (including the VBS_WORKSPACE_DIR/VBCS_REPO_PATH resolution order and the list_repos pointer), so the schema carries the load. The description merely echoes 'by repo-relative path' and adds no format or resolution detail beyond it, matching the baseline 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?

States a specific verb (Read) plus resource (VBCS artifact file) and scoping mechanism (repo-relative path), and enumerates example artifact types (page/flow/chain/service JSON). An agent can distinguish it from write_artifact, list_artifacts, and search_artifacts by the retrieval-by-path semantics, 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?

Usage is only implied: the required 'path' parameter and the 'by repo-relative path' phrasing suggest this is for fetching a known file, in contrast to search_artifacts or list_artifacts for discovery. The description never states when to use it, when not to, or which alternative fits 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 declare it read-only, idempotent and non-destructive, so the safety bar is low. The description still adds genuine behavior beyond that: output streams live to server logs, it requires network access to a live VB backend, and failures surface a plain-language hint. It doesn't say what the audit actually checks, but the disclosure is above the annotated baseline.

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

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

Three tight sentences, front-loaded with the action and followed by operational preconditions. Every sentence carries content; nothing is padding, though the failure-hint detail is slightly incidental.

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

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

With no output schema, the description compensates by noting that output streams live to server logs and that errors include a plain-language hint, covering both the success and failure paths. Missing only what the audit checks and how a caller observes results from 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?

Schema description coverage is 100%, so both repo and appName already carry full detail (defaults, list_repos/list_apps pointers). The description adds only the phrase 'for a VBCS app' and no format or syntax beyond the schema, 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?

States a specific verb (run) and resource (grunt-vb-audit) scoped to a VBCS app, which separates it from run_build and the vbstudio_* build tools. It does not explicitly say how it differs from audit_service_calls, but the audit-vs-build distinction is inferable.

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 points at a prerequisite ('needs the same setup as run_build') and an environmental condition (network access to a live Visual Builder backend), which is useful. However, it never states when to choose this tool over run_build or audit_service_calls, so usage is only implied.

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

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

Annotations only mark it as a non-read-only, non-destructive operation; the description goes further by disclosing that output streams live to server logs, that an environment variable gates web-component apps, and that failures carry a plain-language hint. It omits whether the call blocks until completion or how long a build typically takes, but the added behavioral context is substantive.

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

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

Three tight clauses with no filler, front-loaded with the action before the prerequisites. Slightly dense and could be split for readability, but nothing is wasted.

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

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

With no output schema and no annotations beyond safety flags, the description covers what runs, the prerequisite chain, the conditional env var, and output visibility via live log streaming plus error hints. What is missing is how results/artifacts are retrieved after the build completes.

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 repo and appName are already fully documented in the schema, including the list_repos/list_apps discovery pointers. The description adds no parameter-level detail (the ENV var mentioned is not a parameter), 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?

States a specific verb and resource ('Run grunt-vb-build for a VBCS app'), so the agent knows exactly what operation executes rather than a generic 'build'. It does not distinguish itself from the sibling vbstudio_trigger_build or explain how the two build paths differ, leaving the sibling boundary 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?

Gives an explicit prerequisite ('Needs setup_build_tools first') and a conditional requirement ('VB_BUILD_COMPONENT_EXCHANGE_URL for apps using web components'), which is real when-to-use guidance. It stops short of stating when to prefer this over vbstudio_trigger_build or how it relates to vbstudio_build_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 declare readOnlyHint/idempotentHint/destructiveHint, so safety is covered. The description adds genuinely useful behavioral context beyond that: the default search scope (which file types the default covers) and the substring-vs-regex default mode. It stops short of describing return format or result ordering.

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

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

Three tight sentences, front-loaded with the core action and mechanism. Every clause earns its place: purpose, matching mode default, and default scope. No filler.

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

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

For a dense search tool with no output schema, the description covers purpose, default scope, and matching mode but says nothing about the shape of results or how maxResults/pagination behaves in practice. It is minimally complete but leaves the agent guessing what a result looks like.

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 67%, and the description meaningfully supplements it: it defines the default matching mode for 'query', names 'glob' as the narrowing mechanism, and notes regex activation. This is more than mere restatement, though ignoreCase/maxResults/repo semantics remain only in the schema.

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

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

States a specific verb (Search), the exact resource (artifact file CONTENT), and the mechanism (grep). The word 'CONTENT' and '(grep)' cleanly distinguish it from siblings like read_artifact, list_artifacts, and list_repos, which operate on file presence/listing rather than content.

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 default behavior ('Defaults to webApps/services/settings .js/... files') and how to narrow results ('narrow with glob'), which implies when it's useful. However, it never states when to reach for this over read_artifact or list_artifacts, nor any exclusions, so usage is inferred rather than guided.

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

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

Annotations (readOnlyHint=false, destructiveHint=false) already declare the mutation and safety profile. The description adds genuinely useful context beyond that: it notes the operation can take several minutes, which affects agent timeout/polling decisions. It does not disclose idempotency, network/auth requirements, or what happens on partial failure.

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

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

Three tight sentences, front-loaded with the verb/resource, then rationale, then the duration caveat. No filler and nothing repeated from structured fields.

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

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

For a zero-required-parameter install tool with annotations covering safety and no output schema, the description covers purpose, prerequisite relationship, and runtime cost. Missing only edge-case behavior (already-installed repos, failure modes), which keeps it just under full completeness.

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

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

Schema description coverage is 100%, and the repo parameter's description already documents path resolution, the default, and pointers to list_repos. The description adds only that the target is a repo's dependencies, so it neither compensates for nor enriches beyond the schema; 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?

States a specific verb (Install) plus resource (build dependencies / `npm install`) and immediately ties it to its downstream purpose: enabling run_build / run_audit. The agent can distinguish it from siblings like git_clone or doctor without opening a 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?

Makes the trigger condition explicit — run this so run_build / run_audit work — and names those sibling tools, giving a clear prerequisite relationship. It does not state when NOT to run it (e.g., when deps already installed), so it stops short of full routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely useful behavior the annotations cannot: CSV is returned inline unless outputPath is set, and the all-objects ZIP is always written to disk with the path returned, plus the design-vs-deployment data source.

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 carries the verb, resource, and both modes without filler. The nested parentheticals make it dense to parse but 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 5-parameter read tool with no output schema, the description covers the critical unknown — where the result lands (inline vs. disk path) — and both modes. Only the unglamorous appName/appVersion params and the target enum detail are left to the 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 60%, and the description largely restates what the schema already documents for boName and outputPath rather than adding new detail. The target parameter's design/deployment semantics live only in the schema, and appName/appVersion are undocumented in both places.

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 (Export) and resource (business-object data) and clearly separates two operating modes: single object as CSV vs. all objects as ZIP. It is plainly distinct from the sibling vbcs_import_bo_data, but it never names that sibling to draw the contrast 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?

It gives explicit mode-selection rules — supply boName for one object, omit it for a full ZIP export — and notes the inline-vs-disk behavior tied to outputPath. It stops short of stating when to reach for this over the import tool or any other sibling.

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 destructiveHint=true and openWorldHint=true, and the description reinforces this with the specific blast radius: 'replace' OVERWRITES the object's existing data, versus append which only adds rows. It also discloses the locking prerequisite. It does not cover auth/permission needs or error behavior, so short of a 5.

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 dense sentences; the destructive 'replace' warning is capitalized and front-loaded, and the locking prerequisite is placed last as the pre-call action. No filler.

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

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

No output schema exists, but the description covers the mutation tool's key risks, format constraints, and preconditions, which is enough for correct invocation. Slight gap: nothing on the 'target' parameter's effect or on partial-failure reporting.

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 67%, and the description compensates by explaining the file-name-to-object-id constraint, that boName defaults to the file name and should be omitted for .zip, and by restating the mode semantics with emphasis on replace. The 'target' parameter's design-vs-deployment distinction is only in the schema, not the description.

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

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

States a specific verb (Import) and resource (business-object data) plus the target environment (standalone VBCS instance), and the accepted file formats. It is clearly distinguishable from sibling vbcs_export_bo_data.

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

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

Gives concrete usage conditions (one object per .csv/.xls/.xlsx with file name equal to object id, or a .zip for several) and a prerequisite ('Lock a live app first'), which maps to sibling vbcs_lock_application. No explicit when-not or a named alternative beyond the lock/unlock 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 readOnly, idempotent, openWorld, and non-destructive, so safety is covered. The description adds useful context that this hits a standalone instance's REST API at VBCS_BASE_URL (implying environment/config prerequisites), but says nothing about pagination, result volume, or auth.

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, front-loaded with the action and resource, with no filler. The parenthetical (VBCS_BASE_URL) and 'via its REST API' are minor implementation detail but plausibly useful for setup.

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

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

No output schema exists, so the description should hint at the return shape, and it does not. For a simple read-only list tool with full annotation coverage this is adequate but leaves the returned application fields/pagination unknown.

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 'filter' parameter, so the baseline is 3. The description contributes no additional meaning about filter syntax, supported operators, or pass-through behavior beyond what the schema 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?

States a specific verb and resource (list applications), the access path (standalone VBCS REST API via VBCS_BASE_URL), and a scoping qualifier ('not backed by a VB Studio git repo'). It is distinguishable from the sibling 'list_apps', though it never names that sibling outright.

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 final clause gives a clear condition for choosing this tool over the git-backed alternative, which is real routing guidance. It stops short of explicitly naming the alternative tool to use instead, so the agent must infer the pairing from the 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 declare the tool as mutating (readOnlyHint=false), idempotent, and non-destructive. The description adds the precondition for export/import, but does not explain what locking entails (e.g., prevents edits) or permission requirements. With annotations covering safety, 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?

One sentence with zero waste, front-loading the action and then the key precondition in parentheses.

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

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

For a simple tool with annotations covering safety and no output schema, the description explains the purpose and precondition. However, it fails to describe the required branchId parameter, leaving a gap for correct invocation.

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

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

The single parameter branchId has 0% schema description coverage and is not mentioned in the description. The agent must infer that branchId identifies the application to lock, but no syntax or meaning is provided.

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

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

States a specific verb 'Lock' and resource 'live application on a standalone VBCS instance', and the parenthetical clarifies the action's role relative to data export/import. The agent can distinguish it from vbcs_unlock_application by the opposite action.

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

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

Provides an explicit when-to-use: 'do this before exporting/importing its data', linking it to sibling tools. It does not state when not to use or explicitly name alternatives, but the context is clear.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the useful scope constraint that this targets a locked live application on a standalone instance, but says nothing about side effects, permissions, or what state change occurs.

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. Brevity is appropriate here, though it arguably trims too much given the undocumented parameter.

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 mutation tool with no output schema and zero parameter documentation, the description leaves a critical gap: what branchId means and how to obtain it. The annotations cover the safety profile, but the calling contract is underspecified.

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

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

Schema description coverage is 0% and the single required parameter branchId is completely undocumented. The description never mentions branchId, so an agent has no idea what value identifies the application to unlock.

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+resource ('Unlock a locked live application') and scopes it to a standalone VBCS instance. It doesn't explicitly name the sibling vbcs_lock_application as the inverse, but the verb choice makes the distinction obvious.

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 on when to unlock, prerequisites (e.g. must be locked first), or how it relates to vbcs_lock_application. The only contextual hint is 'standalone VBCS instance', which is a constraint, not usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the useful output example (e.g. SUCCESSFUL), but says nothing about error behavior for an invalid build number, auth requirements, or what other status values exist.

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 well-formed sentence that front-loads the verb, resource, and distinguishing identifiers with zero waste. Ideal size for a simple status query.

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 status lookup with annotations covering safety and no output schema, the description plus the schema's repo documentation give an agent enough to call it correctly. It could be richer about return values or failure modes, but nothing essential is missing.

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

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

Schema description coverage is only 33% (only repo is documented). The description partially compensates by naming the two required parameters as the build identifiers ('job name and build number'), but adds no format details (e.g. jobName naming convention, buildNumber range) and does not mention the repo parameter at all.

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 (Get) and resource (status of a VB Studio CI build) keyed by job name and build number. The purpose is clear and implicitly distinguishable from trigger/run tools, but it never names a sibling (e.g. vbstudio_trigger_build) to make the selection explicit, so it stops short of a 5.

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 when-to-use guidance, no prerequisites, and no mention of alternatives. The agent is left to infer that this is the post-trigger status check rather than, say, run_build or vbstudio_job_params.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds the return format (YAML) but nothing on permissions, repo resolution behavior, or failure modes for unparameterized jobs.

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

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

A single sentence that front-loads the action and resource, then attaches the purpose. No filler and nothing to trim.

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

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

For a two-parameter read tool with no output schema, the description tells the agent what it returns (YAML) and why. The only gap is the undocumented jobName parameter and unstated behavior for non-parameterized jobs.

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 50%: repo is fully documented in the schema while jobName has no description anywhere. The phrase 'a ... VB Studio CI job's parameter definitions' only loosely implies jobName is the job identifier, so the description barely compensates for the uncovered 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?

Specific verb (Get) plus resource (a VB Studio CI job's parameter definitions in YAML). It even names the sibling it feeds into (vbstudio_trigger_build), so an agent can place it in the workflow without opening a 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 clause 'to build the paramsYaml for vbstudio_trigger_build' makes the intended context and downstream consumer explicit, which is strong routing guidance. It stops short of stating when NOT to call it or what happens for non-parameterized jobs, so it falls just below the top tier.

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 non-read-only, open-world, non-destructive profile, but the description goes further by stating the return value (the build number), the credential resolution chain (VBSTUDIO_API_TOKEN or username/password falling back to git credentials), and how the API base is derived from the git remote. These are operational details not present in the structured fields. It omits whether triggers are queued, deduplicated, or concurrent.

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

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

Three dense sentences, front-loaded with the action and outcome, followed by environment/auth details. No filler and each sentence carries distinct 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 no output schema, the description correctly states the return value (build number), covers authentication and API base derivation, and links to the parameter helper tool. The only gap is that the required jobName parameter's meaning and accepted values are never described.

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 67%, so the schema documents repo and paramsYaml; the description reinforces the repo-to-git-remote relationship but adds no syntax for paramsYaml beyond pointing at vbstudio_job_params. The required jobName parameter carries no description in either schema or description, so the description does not fully compensate for the coverage gap. 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 verb and resource ('Start a VB Studio CI job') and immediately clarifies the deploy/pipeline-step use case, which separates it from siblings like vbstudio_build_status (status polling) and vbstudio_job_params (parameter discovery). An agent can identify the operation 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 parenthetical 'also how you run a deploy job/pipeline step' tells the agent this tool covers both CI and deploy triggers, and it points to vbstudio_job_params for parameter construction. It stops short of explicit when-not-to-use or a direct comparison with run_build, so it is clear context but not full routing guidance.

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

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

Annotations already declare readOnly=false, idempotent=true and destructive=true. The description adds genuine extra context by disclosing two refusal behaviors (.json paths must contain valid JSON; paths outside the repo are rejected), which the annotations cannot convey. It does not, however, address what the destructive flag means in practice — whether an existing file is overwritten, whether parent directories are created, or what happens on success.

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 with zero filler, and the core action is front-loaded before the constraint clauses. Every sentence earns its place.

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

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

For a three-parameter mutation tool with full schema coverage and annotations carrying the safety profile, the description covers purpose and refusal conditions adequately. The remaining gap is the absence of any statement about overwrite/create semantics, which matters for a tool flagged destructive.

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

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

Schema description coverage is 100%: the schema already documents path, repo, and content, including the repo resolution rules and the list_repos cross-reference. The description's 'repo-relative path' merely restates the schema and adds no syntax or format detail, 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?

States a specific verb (write) and resource (VBCS artifact file) with its scoping rule (repo-relative path), which is clearly distinguishable from read_artifact, list_artifacts, and search_artifacts. It stops short of naming those siblings explicitly, so it is clear but not fully differentiated.

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 never says when to use this tool versus alternatives, nor does it state prerequisites (e.g., that the file is overwritten, or that the repo must already be cloned via git_clone). Usage is only implied by the verb 'write'.

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