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

With no annotations, the description carries the behavioral burden and does so well: it discloses the 5-30 minute runtime, that progress notifications keep long-running clients alive, the 60-second Codex default timeout risk, and that the run produces an artifact recorded for upload. It does not state authentication requirements or where artifacts are written.

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 core purpose is front-loaded in the first sentence, followed by runtime expectations and the timeout fallback. Three sentences with little waste, though the Codex-specific timeout detail is somewhat lengthier than strictly necessary.

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?

There is no output schema and no annotations, so the description must cover behavior itself; it explains runtime, timeout handling, and the artifact handoff to buildtree_upload. It stops short of describing the return payload or permission prerequisites, which leaves a small gap for a long-running mutation-style tool.

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

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

Schema coverage is only 50%: dir and platform are documented in the schema, but tailLines and timeoutSeconds have no descriptions in either the schema or the description. The description's 'for one platform' wording marginally reinforces the platform parameter, but it adds no syntax or guidance for the two undocumented numeric 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 action (run the build command from buildtree.config.json) with a defined scope (one platform) and a downstream effect (record the artifact for buildtree_upload). An agent can distinguish this from sibling tools like buildtree_upload or buildtree_list_builds without opening any 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?

It gives explicit when-to-use context (config-driven build for one platform) and an explicit when-not/alternative path: if the client enforces a short timeout, run `npx @buildtree/cli build android` in a shell and then call buildtree_upload with the artifact path. This names both the failure condition and the substitute workflow.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the cardinality constraint and that a slug is returned, but for a mutation tool it says nothing about authentication requirements, whether creation is idempotent, or side effects — gaps that matter given the presence of buildtree_login siblings.

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 zero filler; the core action is front-loaded and the return-value note is appended where it is most useful.

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 sensibly notes the returned slug, and the single required parameter is fully covered by the schema. The only shortfall is omission of auth/precondition context, which is relevant for a creation tool.

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

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

Schema coverage is 100% for the single 'name' parameter, so the schema already documents it fully. The description adds only the 'one per app' framing and does not enrich the parameter's meaning beyond what the schema states, which is the baseline 3 case.

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 ('Create a buildtree project') and adds a scoping rule ('one per app') plus the downstream purpose of the return value ('slug to use in buildtree_upload'). This clearly distinguishes it from sibling read tools like buildtree_list_projects, though it doesn't name a specific sibling it must not be confused with.

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 'one per app' implies when the tool should be used, but there is no explicit when-to-use/when-not guidance or reference to alternatives such as buildtree_list_projects or buildtree_detect_project.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds meaningful context beyond that: 'Filesystem only; runs nothing' clarifies it will not execute builds or side effects, and 'suggest' plus 'notes' signals the output is advisory rather than applied. It could still say more about what the notes contain.

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 that front-load the resource and frameworks, then the scoping constraint and workflow hint. Nothing is wasted, though the trailing config-review sentence is slightly advisory 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?

Despite no output schema, the description conveys what the tool returns (suggested commands, artifact paths, notes) and its safety profile. It is nearly complete for a single-parameter read-only detector, needing only clearer downstream routing.

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

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

With a single parameter at 100% schema coverage, the schema already documents 'dir' as an absolute path. The description adds nothing about the 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 (inspect) and resource (a directory of a mobile app) plus the concrete output: suggested buildtree.config.json commands and artifact paths. It distinguishes itself from write_config and build by being read-only and suggestion-only, though it never names a sibling 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?

Implies a workflow position ('Review the notes before writing the config'), which suggests using this ahead of buildtree_write_config. However, it gives no explicit when-to-use/when-not guidance and does not name the alternative tool directly.

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

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

The readOnlyHint=true annotation establishes the safety profile, and the description does not contradict it. It adds the mild constraint that the build must already exist, but says nothing about whether links expire, whether they require authentication to redeem, or what the QR code encodes.

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 telegraphic phrase with zero waste, front-loading the output (install URLs, QR code) ahead of the input constraint. It is a noun phrase rather than a sentence, which makes it slightly terse even for a simple tool.

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

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

With only two parameters, no output schema, and a simple read annotation, the definition is nearly adequate but leaves the return shape (which platforms, what URL formats, whether the QR image is inline) entirely unspecified. An agent can call it, but cannot anticipate the response.

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

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

Schema description coverage is 0%, so the schema documents only types and a UUID pattern. The description partially compensates by naming the QR code, mapping loosely to the qr boolean parameter, but leaves buildId's provenance and the qr default (true) unexplained.

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 (install URLs and a QR code) tied to a specific qualifier (an existing build id), so an agent knows it retrieves install artifacts for a given build. It does not, however, contrast itself with near siblings like buildtree_list_builds or buildtree_upload, so differentiation depends on 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?

"for an existing build id" is the only hint that this tool presumes a prior build. There is no guidance on when to reach for it versus list_builds, no mention of where the build id comes from, and no stated 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds useful behavior (sort order newest-first, filterable by env/branch), but says nothing about pagination despite a limit parameter, nor about result caps or empty-project behavior. With annotations carrying the safety profile, this is a modest addition.

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 resource first, then ordering, then returned fields, then filtering. It is dense but every clause carries information; 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?

With no output schema, describing the returned fields is the right move, and the description does so. The main gap is pagination/limit behavior for a list tool, which an agent would need to call it confidently.

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%: project and branch are described in the schema, while env and limit are not. The description partially compensates by framing env and branch as filters, but adds no semantics for limit (page size? truncation?) beyond the schema's default/max. Baseline 3 fits a half-documented 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 (list), resource (builds), and scope (in a project, newest first), and enumerates the returned fields (ids, env, branch, version, open feedback counts). It is clearly distinguishable from siblings like buildtree_list_feedback and buildtree_list_projects by resource, 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?

The closing sentence 'Filter by env or branch' implies how to narrow results, but there is no guidance on when to use this tool versus alternatives (e.g. buildtree_build or buildtree_list_feedback) or on prerequisites like authentication/project existence. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, so safety is covered, yet the description adds genuinely new behavioral context beyond structured fields: the returned payload includes screenshot URLs and, critically, the feedback text is untrusted tester-authored data that should be treated as data rather than instructions. It omits pagination/limit behavior, keeping 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?

Three compact sentences, front-loaded with what the tool returns, then filtering, then the safety caveat. Every sentence carries distinct information with 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?

With readOnlyHint set, no output schema, and five parameters, the description supplies the return shape (feedback plus screenshot URLs), the filter semantics, and the untrusted-input warning that an agent genuinely needs. The only gap is limit/pagination behavior, which is minor against the schema default.

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 20% (just 'project'), so the description must compensate, and it does for three of five parameters: the parenthetical maps to the kind enum (bug/works/suggestion), 'one build' maps to buildId, and 'open items' maps to status. Only limit (default 50, max 100) is left undocumented.

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) and resource (feedback testers sent from install pages), enumerates the feedback kinds, and notes that screenshots come back as URLs. None of the sibling tools (builds, projects, config, login) overlap, so an agent can select this immediately.

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?

Mentions two narrowing conditions ('filter to one build or to open items'), which implies when the tool is useful, but gives no explicit when-to-use vs. alternatives, no prerequisites, and no statement of what to do instead when neither filter matches. Usage is implied rather than specified.

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?

readOnlyHint=true already tells the agent this is a safe read with no side effects. The description adds one piece of real context beyond that — results are permission-scoped to what 'this account can upload to' — but says nothing about return shape or ordering. With annotations carrying the safety profile, this is adequate but thin.

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, with the purpose front-loaded and the actionable next step immediately after. 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 zero-argument, read-only list tool with no output schema, the description covers purpose, scope, and follow-up action. The one small gap is that it doesn't hint at what a project entry contains (e.g., the slug field it tells you to reuse), but that is minor 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?

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter-related value is expected or missing.

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 ('List the buildtree projects') with a meaningful scope qualifier ('this account can upload to'), which distinguishes it from buildtree_list_builds and buildtree_list_feedback. It does not, however, explicitly contrast itself with those list siblings.

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 usable forward guidance: 'Use the slug with buildtree_upload' tells the agent what to do with the result and links to the dependent sibling. There is no statement of when NOT to use it or of preconditions (e.g., login/auth state), so it stops short of a 5.

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

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

No annotations are present, so the description carries the full burden. It discloses the key behaviors: a URL is returned, the tool attempts to open it automatically, user approval is required, and critically it never returns a token. It stops short of covering permission requirements, timeouts, or what happens on rejection.

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 tightly packed sentences with zero filler; the core output (a URL for the user to approve) and the follow-up call are 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 no output schema, the description appropriately explains the return value (a URL, never a token) and the required next step. What an agent needs to invoke and chain this tool is present; only edge-case behavior is absent.

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 apiUrl parameter is fully documented in the schema (100% coverage), so the baseline is 3. The description adds no format or default-behavior detail 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 ('Start a browser login') and immediately clarifies the multi-step nature of the operation. It also names the sibling buildtree_login_status as the required follow-up, distinguishing it from the other login-related 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?

Explicitly routes the agent: 'Then call buildtree_login_status with the pairId' tells exactly what to do after this tool and with what value. It lacks an explicit when-not-to-use clause, but the two-step flow 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?

With no annotations, the description carries the full burden and it does disclose real behavior: bounded polling via waitSeconds and a persistent side effect (the token is stored for this machine and shared with the CLI). It omits timeout/failure outcomes and whether the stored token expires, which keeps it from 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?

Three short sentences with no filler; the core action and its dependency on buildtree_login are front-loaded, and the retry instruction closes the loop.

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 convey the possible result states; it hints at "pending" but never describes the approved/failed outcomes or what the stored token looks like. Combined with the undocumented required parameter, the definition is workable but leaves real gaps.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It explains waitSeconds semantically (bounded polling window) but says nothing about pairId, the required opaque 16-64 character identifier, not even that it comes from buildtree_login's response.

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 (wait for/poll a login approval) on a specific resource and explicitly ties itself to the sibling buildtree_login that starts the flow. An agent can tell this apart from the other buildtree_* tools 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?

It names the predecessor tool that must run first and gives an explicit retry protocol ("Call again while it reports pending"), which is exactly the operational guidance an agent needs. It does not state when not to call it, so it falls just 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the return payload and the visibility implication of publishing a checkpoint ('the build QA should grab'), plus the defaulting of `file` and `project`. However, it says nothing about authentication/permissions, whether an upload overwrites an existing build, or failure modes for a mutation-style 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?

Three tight sentences, front-loaded with the core action and output, followed by the two behavioral conditionals. No filler or redundancy; every clause carries routing or behavioral 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?

No output schema exists, and the description compensates by naming the returns (install URLs, QR image) and the optional release URL implied by the `release` param. For a 6-parameter tool with full schema coverage this is close to sufficient, though auth/prerequisite context is absent.

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 including the default-to-last-artifact and default-project behaviors. The description mostly restates that schema content, adding only the rationale for the `branch` vs no-`branch` split, 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?

States a specific verb and resource ('Upload an .apk, .aab or .ipa to a buildtree project') and even names the return payload ('install URLs plus a QR code image'). This distinguishes it cleanly from siblings like buildtree_build (which produces the artifact) and buildtree_get_install_links (which retrieves links for an existing build).

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 explicit conditional guidance: omit `branch` to publish the environment checkpoint, pass `branch` for a pre-merge preview, and notes `file` falls back to the last buildtree_build artifact. It does not name alternative tools or state exclusions, but the mode-selection rules are clear and actionable.

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

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

With readOnlyHint=true already covering the safety profile, the description adds real value beyond annotations by naming the returned fields (email, organization, plan, limits) and disclosing a failure state (not logged in). It does not describe rate limits or auth requirements, but for a no-arg read tool this is close to complete.

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

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

Three short sentences, zero filler, with the purpose and the "call this first" directive front-loaded before the fallback path. 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 no-parameter read-only tool whose annotations already declare its safety profile, the description covers purpose, invocation ordering, returned content, and the error path. With no output schema, the enumerated return fields are exactly the right compensation.

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 takes zero parameters, so per the baseline there is nothing for the description to disambiguate; the schema is trivially complete. No parameter-level guidance is needed or missing.

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 and scope: the current buildtree login and account, enumerating what is reported (email, organization, plan, limits). It distinguishes itself from buildtree_login by routing on the not-logged-in case, though it never clarifies how it differs from the sibling buildtree_login_status, which an agent could easily confuse it with.

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 sequencing ("Call this first") and a concrete conditional alternative ("If it reports not logged in, use buildtree_login"). The agent knows both when to call this tool and where to go on failure, leaving nothing 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 only supply idempotentHint=true, so the description carries most of the burden and does contribute real behavior: the write is refused unless `overwrite` is true, and artifact paths must be exact (no globs). It does not cover auth requirements or what happens after a successful write.

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

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

Three short sentences, front-loaded with the action, then the payload contract, then the guard condition. No filler or repetition of the 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 3-param tool with a nested object and no output schema, the description covers the key nested semantics and the overwrite rule. It stops short of stating the return/error shape or required permissions, which matters given there is no output schema and only a thin idempotent annotation.

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 `builds` map semantics (platform name to shell command plus exact artifact path, no globs) and the meaning of `overwrite`. `dir` is left to the schema, which documents it 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 names a specific verb+resource (write buildtree.config.json) and immediately clarifies the shape of the `builds` payload and the overwrite-guard behavior. It is clearly distinct from siblings like buildtree_build or buildtree_login, though it does not explicitly contrast itself with any of 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?

Usage is implied (you write a config that maps platforms to commands/artifacts) and the overwrite precondition is stated, but there is no explicit when-to-use guidance, no mention of prerequisites such as running buildtree_detect_project first, and no named alternatives.

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