Local Commander

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

Goes well beyond the annotations: explains the Full Access vs scoped-grant rights model, that timeoutMs is process lifetime capped at 24 hours, that long commands return running IDs in ~2 seconds, that each call is metered as one execution, and that a returned call must not be resent. This is exactly the extra context annotations cannot convey.

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

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

Front-loaded with the primary use case and the critical when-not rule, and every sentence carries information (timeouts, metering, follow-up IDs, retry rule). The sentences are long and dense, which costs a point, but there is 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 high-complexity, 9-parameter, nested-object tool with no output schema, the description covers execution lifetime, result-return modes (inline vs IDs), required identifiers, metering, and the follow-up/stop tools. Nothing an agent needs to call it correctly is missing.

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

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

With schema coverage at 100% the baseline is 3, but the description adds operational meaning: timeoutMs is framed as process lifetime rather than a queue/admission timeout, operationId is a fresh UUID reusable only for retrying the identical call, and sessionId's origin is restated. deadlineAt and efficiencyProfile are left to the schema, but the required-parameter semantics are clarified.

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 ('run a command on the approved computer') and enumerates concrete command families (build, test, Git, package manager, PowerShell). It also carves out scope versus siblings by deferring host-scanning to a decline and pointing at operation_status/operation_output/operation_cancel for follow-up.

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?

Explicit trigger ('when the user asks to run a command'), explicit exclusion ('Do not use to scan or probe hosts other than this computer... decline those instead'), and named prerequisites ('Needs the sessionId from execution_session_open'). It even names the sibling tools for continuing a long-running command.

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=false, destructiveHint=false and idempotentHint=true already declared, the description still adds real value: repairSafe only touches this grant's expired, never-dispatched reservations, never releases unknown executions, never changes local permissions, and old agents degrade to one slot. The "connection health does not prove command authorization" caveat is useful but no permissions or rate-limit details are given.

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 usage trigger is front-loaded and the two paragraphs separate reporting from repair behavior. However, "old agents conservatively use one slot" is cryptic and the second sentence is dense with stacked qualifiers.

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 the description compensates by enumerating what is reported (online state, quota, leases, verified capacity/version). Combined with the repair-safety disclosure, an agent has enough to call this correctly, though deviceId semantics remain unexplained.

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?

Two parameters at 50% schema description coverage; repairSafe carries its own schema description and the prose largely restates it. The required deviceId is undocumented in both places, and the "one slot" fallback behavior is only loosely tied to a parameter.

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

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

The description states a specific verb set (diagnose/report, and safely repair) plus concrete resources: online state, quota, leases, verified native capacity/version. It is clearly distinct from siblings like usage_status or operation_status, though it never names an alternative 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?

"Use after capacity/transport errors" gives an explicit trigger condition. It does not say when not to use it or which sibling (e.g. usage_status) to prefer for pure quota questions, so it stops short of a full routing rule.

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

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

Annotations already declare destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds meaningful scope beyond them: it only affects a grant-owned session and 'does not terminate unrelated processes', which is exactly the blast-radius information an agent needs. Return/pagination behavior is not described, minor for a close call.

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 usage trigger front-loaded ahead of the ownership/non-termination constraints. No filler, though the second sentence packs two distinct constraints without break.

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 for a close operation the essential agent needs (when to invoke, whose session is affected, what is NOT affected) are all present and the annotations cover the safety profile. Missing only explicit sessionId semantics, which keeps it from a 5.

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

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

One parameter (sessionId) with 0% schema description coverage, so the description must carry the load but says nothing about which session identifier to supply or its format. The UUID format in the schema partially compensates, leaving this at a minimum-viable 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 and resource ('closes ... session') and scopes it to sessions 'owned by the authenticated grant', which an agent can distinguish from execution_session_open. It does not explicitly name a sibling or contrasting tool, so it stops just 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?

Gives clear triggering conditions: 'when approved local work is complete or the user asks to stop using the current session.' It covers when to use it but offers no exclusions or comparison against alternatives like operation_cancel.

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 carry the generic flag set (not read-only, not idempotent, not destructive). The description adds genuinely useful behavior: expectDeviceName mismatch opens nothing (a silent no-op guard), startup is metered and counted as one project read, and omitting startup opens only the session.

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?

Front-loaded with the use condition and the critical expectDeviceName guard, then returns, then the startup cost tradeoff. Dense and information-bearing, though a few clauses (return enumeration plus cost note) could be tightened.

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 return shape (authenticated account, device ID/name, session envelope, optional startup context). Prerequisites, the failure mode, and the metering cost are all covered for this 5-parameter nested 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?

With 100% schema coverage the baseline is 3, but the description adds real meaning beyond the schema: it explains expectDeviceName is the PC name the user gave and that a mismatch prevents opening, and characterizes what startup returns and its cost. It does not fully restate required-param prerequisites, keeping it below 5.

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 ('opening a session on the explicitly selected device/workspace') and scopes it precisely enough to separate it from execution_session_close and the discovery siblings. An agent can tell what this does 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?

Gives clear context: use it for the explicitly selected device/workspace, and 'Discover workspace IDs first only when unknown' conditions the discovery path. The prerequisite routing to project_target_resolve is left to the schema rather than the description, and there is no explicit when-not statement, so it falls 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 cover safety (readOnly, idempotent, non-destructive), and the description adds substantial operational context beyond them: each call is metered as one execution, a new operationId is required, short results return inline within ~2 seconds, and longer operations must be polled via operation_status/operation_output without resending. This is exactly the behavioral detail an agent needs to call safely.

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?

Front-loaded with the usage trigger, then the read-only note, required inputs, metering, and async fallback — each clause carries operational weight with little filler. Dense but not 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 carries the return burden and does explain the inline-vs-async result path and polling IDs. It is slightly thin on the shape of the returned entries themselves, but it covers the operationally critical return behavior.

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 sessionId, operationId, path, maxDepth, and the rest. The description reiterates the sessionId/operationId contract but adds no syntax or format detail beyond the schema, making the baseline 3 appropriate.

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

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

The description names a specific verb and resource: listing files and folders within an approved project, which is clearly distinguishable from fs_read/fs_write/fs_search. It could be sharper about how it differs from fs_search, but the core purpose is unambiguous.

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

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

"Use this when the user wants to see which files and folders an approved project contains" gives a clear triggering context, and it notes the prerequisite sessionId from execution_session_open. It does not name alternatives (e.g., fs_search) or state when not to use it.

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

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

Annotations already cover read-only, idempotent, non-destructive semantics, and the description adds meaningful operational context beyond them: each call is metered as one execution, short results return inline within ~2 seconds, and otherwise the returned IDs feed operation_status/operation_output with an explicit 'do not resend the call' instruction. This materially shapes how an agent should behave.

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 with the usage trigger front-loaded and no wasted framing. The async-result sentence is long but each clause (metering, inline vs. deferred, do-not-resend) 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 explains the return model (inline vs. ID-based retrieval) and the metering/auth prerequisites. It omits guidance on the optional deadlineAt and efficiencyProfile parameters and on error or binary-file cases, leaving minor gaps for an eight-parameter tool.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters including line ranges and the deadline/operationId semantics. The description adds little parameter-level detail beyond restating where sessionId and operationId come from, 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 (read) and resource (text file) plus scope (approved project, whole or by line range), which cleanly separates it from siblings like fs_list, fs_search, fs_write, and fs_replace. An agent can identify the tool's function 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?

Gives a clear trigger ('when the user wants to read a text file') and prerequisites (sessionId from execution_session_open, a new operationId). It does not explicitly name alternatives such as fs_search or fs_list, nor state exclusions like binary files, so it stops short of full when-not 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 this is a non-read-only, destructive, idempotent, non-open-world write. The description adds genuinely new operational context beyond that: metering (one execution per call), expected inline latency (~2 s), the async fallback via operation_status/operation_output, and the instruction not to resend. It omits failure behavior, such as what happens when oldText is absent or the edit is refused, so it falls 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?

Four sentences, front-loaded with the triggering condition before mechanics, and the async/polling guidance comes last where it belongs. Dense but every sentence carries information; 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 10-parameter destructive mutation with no output schema, the description covers the session/operation lifecycle, metering, latency, and the async-result contract, which is the key operational knowledge an agent needs. It leaves out error/refusal conditions and the direct-vs-async decision boundary, keeping it just under complete.

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

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

Schema description coverage is 100%, so every parameter including oldText/newText/replaceAll/expectedSha256 is already documented in the schema, establishing the baseline of 3. The description only reinforces the origin of sessionId and the freshness of operationId, which the schema already states, so it adds little semantic value on top.

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: 'replaces exact text with new text' inside a file, scoped to 'an approved project'. This is a precise sub-operation distinguishable from a whole-file write. However, it never names the obvious sibling fs_write or contrasts itself with it, so sibling differentiation is left to inference.

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

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

Gives an explicit trigger condition ('Use this when the user asks to change part of a file in an approved project'), which frames it as a partial-edit tool. It stops short of stating when NOT to use it (e.g. whole-file writes via fs_write) or prerequisites like acquiring a session first, beyond the pointer to execution_session_open.

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

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

Goes well beyond the annotations (readOnly, idempotent, non-destructive, closed-world) by disclosing the async contract: metered as one execution, inline results within ~two seconds, otherwise retain the returned IDs for operation_status/operation_output and do not resend. This is exactly the behavioral context an agent needs to call it correctly.

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?

Front-loads the when-to-use trigger, then return shape, safety, prerequisites, and the async fallback in tightly packed sentences with no filler. Each sentence carries a distinct, load-bearing fact.

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 nine-parameter, nested-object, no-output-schema async tool, the description covers the critical agent-facing decision (inline vs. deferred result) and prerequisite IDs. It omits error handling and deadline/idempotency behavior, but those live in the schema, so the gap is minor.

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

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

Schema description coverage is 100%, so all nine parameters are already documented in the schema, including sessionId's origin and operationId's freshness requirement. The description restates these without adding 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 and resource ('find text in the files of an approved project'), which is inherently distinguishable from fs_read (read a file), fs_list (enumerate files), and fs_write/fs_replace. An agent can select this over its 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?

Opens with an explicit when-to-use condition ('Use this when the user wants to find text...'). It gives clear context but names no exclusions or alternative tools for the read-a-known-file case, 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 destructiveHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description goes beyond them with genuinely useful operational context: the execution_session_open dependency, per-call metering, the ~2s inline-result window, and the instruction to poll operation_status/operation_output rather than resend.

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

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

Four sentences, front-loaded with the use case, then prerequisites, then the async/return contract. 'Changes files on the computer' is mildly redundant with the destructive annotation but is short and reads as plain-language clarification rather than 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 9-parameter mutation tool with a nested object and no output schema, the description covers the essentials an agent needs: the required session, the fresh operationId per call, metering, and the fallback polling path when the result is not returned inline. It omits error/refusal semantics (e.g. the expectedSha256 conflict and overwrite guard), which are only visible in 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 coverage is 100% across 9 params, so the schema already documents overwrite, expectedSha256, deadlineAt, idempotencyKey and efficiencyProfile with real semantics. The description only reinforces sessionId/operationId and their retry relationship, 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 states a specific verb and resource ('create a file or replace a file's whole text') and uses 'whole text' to implicitly delimit itself from the partial-edit sibling fs_replace. It stops short of naming that sibling, so the distinction must still be inferred.

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?

'Use this when the user asks to create a file or replace a file's whole text in an approved project' gives a clear triggering condition and scopes it to approved projects/workspace roots. It does not explicitly state when to prefer fs_replace or what to do when no session is open.

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 cover read-only/idempotent/non-destructive, and the description adds genuinely new traits: each call is metered as one execution, short results return inline within ~2 seconds, and longer results must be fetched via the returned IDs rather than by resending the call. That cost, latency and retry guidance goes well beyond what the annotations declare.

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 with zero filler; the trigger is front-loaded, then the safety/cost facts, then the return-handling rule. Every sentence carries operational information.

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

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

For an 8-parameter tool with no output schema, the description covers the two things an agent cannot infer: the metering cost and the inline-vs-async result contract with the exact follow-up tools. Remaining fields (deadlineAt, efficiencyProfile, path/file) are fully documented in the schema, so nothing material is missing.

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

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

Schema description coverage is 100%, so every parameter including sessionId, operationId, deadlineAt, staged, path, file and efficiencyProfile is already documented in the schema. The description's remarks about sessionId provenance and a fresh operationId largely restate the schema, so it adds little beyond the baseline.

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

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

The description gives a specific verb and resource — seeing the uncommitted or staged changes — and scopes it to an approved project, which cleanly separates it from git_status (working-tree status) and git_log (history) among the siblings. An agent can pick this tool 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 states a clear trigger condition ('when the user wants to see the uncommitted or staged changes') and names the follow-up path (operation_status/operation_output) when the result is not inline. It does not, however, state when NOT to use it or name a sibling alternative (e.g., git_status vs git_diff) explicitly, so it falls short of full when/when-not/alternatives coverage.

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 cover read-only/idempotent/non-destructive, yet the description still adds substantial context: metered as one execution, sessionId provenance, the ~2 second inline threshold, and an explicit 'do not resend the call' instruction. That is exactly the beyond-annotation disclosure the bar asks for.

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 triggering condition is front-loaded and every sentence carries information (usage, safety, required inputs, async behavior). It is slightly dense and mixes purpose, params, and lifecycle in one block, but 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 metered session-scoped tool with no output schema, the description covers the full lifecycle: how to get the session, the per-call billing, the fast-path return, and the async fallback to operation_status/operation_output. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and each field (path, limit, sessionId, operationId, deadlineAt, idempotencyKey) is documented in the schema itself. The description's mention of sessionId and a 'new operationId' restates schema content rather than adding syntax or edge-case 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?

States a specific verb and resource ('recent commit history of an approved project') and opens with the exact trigger phrasing 'Use this when the user wants...'. An agent can distinguish it from git_diff and git_status 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?

Gives a clear when-to-use trigger and names the follow-up tools (operation_status, operation_output) for the async case. It never explicitly excludes git_diff/git_status-style scenarios, so the sibling routing 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds material behavior beyond them: each call is metered as one execution, results arrive inline in roughly two seconds or fall back to an async flow, and the agent must not resend the call but instead reuse the returned IDs with operation_status and operation_output.

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

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

Four sentences, no filler, and the trigger condition is front-loaded. The dense latency/fallback sentence earns its length by telling the agent exactly what to do next instead of blindly retrying.

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 describing the return path: a short inline result versus IDs the caller keeps for operation_status and operation_output. Combined with the metering cost and prerequisite session, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, and the schema itself already explains path, sessionId provenance, deadlineAt, and operationId semantics, so the baseline is 3. The description largely restates the required parameters (sessionId from execution_session_open, a new operationId) and adds only workflow framing rather than new parameter-level meaning.

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: retrieving the Git branch and changed files of an approved project. This scope is separable from git_diff (content of changes) and git_log (commit history) by inference, but the description never names a sibling, so it lands at 4 rather than 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?

"Use this when the user wants the Git branch and changed files of an approved project" gives a clear triggering condition, and the session/operation prerequisites are spelled out. It stops short of explicit exclusions or naming alternatives such as git_diff or git_log, so no 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 read-only, idempotent, non-destructive, closed-world behavior, and the description still adds material context: 'other hosts are refused', each call is 'metered as one execution', results are returned inline 'within about two seconds', and the agent must not resend but instead poll operation_status/operation_output. That async/timeout/security disclosure goes well beyond the structured hints.

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?

Single dense paragraph with the trigger clause front-loaded, followed by behavior, prerequisites, and the async fallback in a logical order. Every sentence carries information, though the run-on density makes it slightly harder to scan than an ideal definition.

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 an 8-parameter tool with nested objects and no output schema, the description supplies the missing pieces: what is returned (status and bounded body), the latency expectation, the async continuation path, and the security boundary. It omits guidance on deadlineAt and header usage, but those are covered by the schema, so nothing essential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-references the schema cannot express: sessionId comes from execution_session_open, operationId must be new per call, and metering ties to the call itself. It does not explain deadlineAt or efficiencyProfile, but those are documented 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 and resource ('sends a GET or HEAD request to a localhost URL') plus the returned artifacts (status and bounded body). The GET/HEAD framing implicitly separates it from localhost_send, which handles other methods, so an agent can route between them.

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

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

Opens with an explicit trigger ('Use this when the user wants to check an approved service') and states the prerequisite sessionId source and the operationId requirement. It also prescribes the follow-up path (operation_status/operation_output) when the result is not inline. It never explicitly names localhost_send as the alternative for non-GET/HEAD traffic, so the exclusion 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?

Goes well past the annotations: it warns the call can mutate the service's data, that non-local hosts are refused, that each call costs one metered execution, and it describes the async contract (inline result within ~2s, otherwise poll operation_status/operation_output and do not resend). That is exactly the operational context the destructive/idempotent hints do not convey.

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

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

Front-loads the trigger condition, then layers scope limits, prerequisites, cost, and result handling in four tight sentences with no filler or repetition.

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

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

Handles the hard parts of a 9-parameter, nested, no-output-schema tool: async result retrieval, metering, host restriction, and retry guidance. It leaves the notion of an 'approved service' (how approval is established) and failure/refusal modes largely unexplained.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by tying sessionId to execution_session_open, specifying that operationId must be new per call, and framing the call against the metering model. It does not add meaning for url/body/headers beyond what the schema already documents.

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 (send) plus the exact method set (POST/PUT/PATCH/DELETE) and the resource (approved local service), which cleanly separates it from the sibling localhost_get. An agent can select it 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?

Opens with an explicit trigger ('Use this when the user asks to send...') and names prerequisites (sessionId from execution_session_open, a new operationId), plus the metering cost. It never explicitly routes GET traffic to localhost_get, so the exclusion is only implied by the method 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?

The annotations already declare destructiveHint=true, idempotentHint=true, and non-readOnly, so the safety profile is covered. The description adds real value beyond them: cancellation is only a request and does not prove a running local process terminated, and the tool stays available under quota exhaustion. It still omits permissions needed and what happens to an already-completed 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?

Two dense sentences, front-loaded with the invocation trigger followed by the key behavioral caveat. No filler or repetition. Slightly compressed phrasing, but every clause carries 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 could have described the response, but for a one-parameter cancellation it covers the critical semantics: ownership scope, asynchronous nature, and quota-independent availability. The main remaining gap is where operationId comes from and how to confirm actual termination.

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% for the single required operationId, and the description says nothing about it - not where to obtain it (e.g., from operation_status or command_run), nor what scope it must belong to. The schema's uuid format/pattern documents the shape, but the description fails to compensate for the missing parameter guidance.

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

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

The description states a specific verb and resource (stop/cancel an operation) and narrows scope to operations 'owned by the authenticated grant', which separates it from general command or session tools. It does not explicitly name or contrast with siblings like operation_status or operation_output, so it falls short of full sibling differentiation.

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

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

It gives an explicit trigger: use when the user asks to stop an operation. That is clear context for invocation. However, it states no exclusions or alternatives (e.g., use operation_status to merely inspect, or execution_session_close for a session), so the routing guidance is incomplete.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds real context beyond them: output is bounded, it does not consume execution units, and availability depends on the connected device retaining the output — a meaningful limitation an agent needs.

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

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

Two sentences, front-loaded with the purpose and followed by the operational constraints. No filler; every clause carries 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 at least names the return payload (stdout/stderr, bounded) and the key precondition. It could go further on truncation behavior or result shape, but for a read tool with full annotation coverage this is close to sufficient.

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

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

Schema description coverage is 0%, so the description bears full responsibility for explaining operationId and childExecutionId. It only gestures at the relationship (a child execution owned by a grant and session) without clarifying which identifier is which or the ownership/validation semantics, leaving the two required UUIDs largely uninterpreted.

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 (retrieve) and resource (bounded stdout and stderr for a child execution), and scopes it to the authenticated grant and active session. It is distinguishable from operation_status and operation_cancel, though it never names a sibling explicitly to sharpen the boundary.

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?

Opens with "Use this to retrieve..." and gives a precondition (requires the connected device to retain the output, active session), which implies when it applies. However, it never states when NOT to use it or points to operation_status / command_run as alternatives for related needs.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), yet the description still adds non-obvious behavior: no execution-quota consumption, no work dispatched, recovery diagnostics surfaced for rejected/unknown children, and a conditional auth requirement (devices:read). The devices:read clause is somewhat terse, keeping this 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 sentences, front-loaded with the use case, then the non-effects, then the edge-case behavior. No filler or restatement of the title. The final sentence is dense with jargon but each clause 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 and a single parameter, the description carries the load well: it covers purpose, non-effects, quota, auth, and diagnostics for rejected/unknown children. It never characterizes the returned state shape, which would be the remaining gap for a status-reporting 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?

One parameter with 0% schema description coverage; the schema supplies type/format/pattern but no meaning for operationId. The description implies the value is an operation the authenticated grant owns, which slightly helps an agent know where to obtain it, but it never explains or names the parameter itself.

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+resource ('current state of an operation') and adds a real scope qualifier ('already owned by the authenticated grant'). It does not name a sibling, so an agent must infer the split from operation_output and operation_cancel rather than being told, but the core purpose is unambiguous.

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

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

It gives a concrete trigger ('when the user needs the current state of an operation') and negative constraints that route the agent away from the wrong tool ('does not dispatch work', 'no repair or replay is performed'). It stops short of explicitly naming operation_output/operation_cancel as the alternatives for output retrieval or cancellation.

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 and non-destructive, and the description adds substantial behavior on top: each call is metered as one execution, sessionId must come from execution_session_open, results return inline in roughly two seconds or fall back to async polling via operation_status/operation_output, and the call must not be resent. This is exactly the extra context annotations cannot carry.

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?

Front-loads the when-to-use condition, then stacks the operational constraints (auth source, metering, latency, async fallback, no-resend) in a dense but readable way. Every clause carries information; the only minor weakness is that the run-on final sentence packs several distinct rules together.

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 carries the return-behavior burden and does so: it explains the inline short-result case, the ~2s threshold, and what to do with returned IDs when the result is not inline. Combined with 100% schema coverage, an agent has everything needed to call and follow up correctly.

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

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

Schema description coverage is 100%, so every parameter (including deadlineAt, idempotencyKey and efficiencyProfile) is already documented in the schema. The description restates that sessionId comes from execution_session_open and that operationId must be new, but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific resource and outcome: the stable identity (repository root and remote) of a project folder. It also positions itself in the pipeline relative to project_target_resolve and project_target_register, so an agent can distinguish it from the other project_* 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 explicit triggering context ('when you need the stable identity of a project folder') and an ordering rule ('before project_target_resolve or project_target_register'). It does not state any exclusion or negative case for when to skip it, but the usage context is 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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds genuinely new context beyond them: entries can be missing and absence means "unknown" rather than "does not exist," and the result carries no device-scan or execution-quota data.

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

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

Two terse clauses, front-loaded, with no filler or repetition. It is telegraphic to the point of being fragmentary, but every clause conveys scope or completeness information.

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

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

For a paginated list tool with no output schema and no parameter documentation, the description covers result scope and the important completeness caveat, but omits how pagination works (limit/afterProjectId) and what a returned entry looks like. Adequate, with a clear gap around paging.

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 is required to compensate and it does not: neither limit nor afterProjectId is mentioned, and the cursor-pagination contract implied by afterProjectId is never explained. Parameter names and the UUID pattern/defaults in the schema carry all the meaning, which is the minimum for a low-coverage schema.

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

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

The description names the resource and its ownership scope ("Account-owned project registry"), and the title supplies the verb ("List registered projects"), so the action is unambiguous. It does not, however, differentiate itself from close siblings such as project_snapshot, project_identity, or project_target_list.

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

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

Usage is only implied: an agent can infer this is the enumeration call for account projects, and "No device scan or execution quota" mildly excludes device/inspection use cases. There is no explicit when-to-use statement and no named alternative (e.g., project_target_list for per-project targets), leaving selection largely to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds cost and lifecycle context that annotations cannot: one metered execution per call, ~2 second inline return, otherwise retain IDs for operation_status/operation_output rather than resending. That is exactly the kind of behavioral detail an agent needs for scheduling and retry decisions.

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?

Front-loads the trigger condition, then prerequisites, then the result-handling rule, with no filler sentences. It is dense and runs long for a single paragraph, but each clause carries operational meaning (cost, timing, retry guidance).

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

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

For a complex tool (8 params, nested efficiencyProfile, no output schema) the description covers the return path: short result inline in ~2s or async IDs to poll. It stops short of describing what 'bounded summary' contains or what happens on timeout/failure, but the essential calling contract is present.

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

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

Schema description coverage is 100%, so the schema already documents path, taskId, startup, deadlineAt, idempotencyKey and efficiencyProfile. The description only restates sessionId provenance and operationId freshness, which the schema already says; it adds no new syntax or constraint detail. 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 (bounded summary of an approved project's files and Git state, plus policy/task continuation under startup). An agent can distinguish this from fs_list, git_status and git_diff because it is framed as a combined, bounded overview rather than a listing or diff.

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 clear triggering condition ('when the user wants an overview of an approved project') plus hard prerequisites: sessionId from execution_session_open and a fresh operationId. It also routes long-running results to operation_status/operation_output and warns against resending, but it never names an alternative tool for the narrow case (e.g. plain file listing or git status), so no explicit exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description does add real beyond-annotation behavior: offline locations remain registered and there is no fallback or repository scan, which tells the agent results may be stale/offline and are not derived. The phrasing is terse and unexplained, limiting the credit.

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 with no filler, but they are sentence fragments rather than a front-loaded statement of purpose, and vague wording ('Offline locations stay registered') costs clarity per word.

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, yet the description does not describe the returned target shape, pagination via afterTargetId, or ordering. For a listing tool with three undocumented parameters and only annotation-level safety info, the description is materially incomplete.

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% across three parameters (projectId, limit, afterTargetId pagination), and the description supplies no parameter meaning at all — not the required project UUID, the limit default of 20, or the cursor semantics of afterTargetId. Nothing compensates for the total 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?

The description is a noun-phrase fragment ('Explicit device/workspace/environment targets and verification metadata') that describes the resource but never states the verb — only the title 'List project locations' reveals it is a listing operation. Siblings project_target_register and project_target_resolve are not addressed, so the agent must infer the distinction from the name alone.

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

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

'No fallback or repository scan' hints at a scope boundary but reads as a cryptic negative rather than a when/when-not rule. It never tells the agent when to pick this over project_target_register, project_target_resolve, or project_snapshot, and no prerequisites are given.

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

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

Annotations only cover safety flags (readOnly=false, idempotent=false, destructive=false). The description adds real behavioral context beyond them: a metered, authenticated identity read must precede the call, existing metadata must match, and it performs no clone/scan/install. It omits what the response returns and any failure/rollback behavior, but the auth prerequisite and matching requirement are meaningful disclosures.

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 with no filler, and the core action is front-loaded ahead of constraints. The 'metered authenticated native identity read' phrasing is jargon-dense but earns its place as a precondition.

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 7-parameter write tool with no output schema and only shallow annotations, the description covers prerequisites and exclusions but leaves most parameters undefined and says nothing about the result of the call. Adequate but with clear gaps given the schema's 0% coverage.

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% across 7 required parameters, so the description carries the full explanatory burden. It only gestures at 'stable project/target UUIDs' and metadata matching, leaving deviceId, workspaceGrantId, environment, relativePath, and displayName entirely unexplained. This is insufficient compensation for a total 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: 'Register one owner-selected repository location.' An agent can tell this apart from project_target_list or project_target_resolve by the act of registering. It stops short of naming those siblings explicitly, so it lacks full differentiation.

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

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

Gives a clear precondition ('after a metered authenticated native identity read') and negative scope ('No clone, scan, install or environment fallback'), telling the agent both when this applies and what it will not do. It does not name an alternative tool for the excluded cases, so it falls just short of explicit 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 readOnlyHint=true and destructiveHint=false, so the description goes beyond them by disclosing that the read is 'metered' (cost implication), that it 'never switches device or creates metadata' (explicit side-effect exclusion), and by enumerating the possible resolution states. It does not explain why idempotentHint is false for a read, but nothing is contradicted.

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 purpose and the return states front-loaded, and the side-effect exclusions placed second. Dense but no filler; the metered/identity phrasing is the only mild cost.

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 usefully enumerates the return states, and annotations cover the safety profile. But for a three-parameter tool with 0% schema coverage, the unexplained previousTargetId leaves a real hole in an otherwise adequate definition.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it only alludes to 'one registered target' and never explains projectId, targetId, or the optional previousTargetId. The role of previousTargetId in particular is completely opaque from both the schema and 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?

The description states a specific verb and resource ('identity read for one registered target') and enumerates the return states (resolved/unknown/offline/stale/mismatch), which distinguishes it from siblings like project_target_list and project_target_register. It is somewhat jargon-heavy ('metered native identity read'), but an agent can tell what the tool does.

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

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

The phrase 'On-demand metered' implies this is invoked deliberately rather than as part of a flow, and 'never switches device or creates metadata' acts as a when-not signal. However, it never names an alternative (e.g., project_target_list or project_identity) or states the condition that selects this tool over them, 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 already establish read-only/idempotent/non-destructive, yet the description adds real behavioral content: it explicitly says it does not reserve or consume quota, and prescribes the unlimited-plan edge case (report unlimited, suppress limitUnits/availableUnits, keep deviceLimit and executionSlots limited). That is behavior beyond what the annotations convey.

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

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

Three sentences, front-loaded with the usage trigger, then the safety note, then the edge case. Every sentence carries distinct information with no 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?

There is no output schema, so the description must carry return-value semantics — and it does, naming the relevant response fields and the unlimited-plan interpretation rule. Combined with annotations covering the safety profile, nothing needed to call or interpret this tool is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The field names it references (limitUnits, availableUnits, unlimitedExecutions) belong to the response, not the input 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 and resource — reads how much managed execution allowance is reserved, consumed, or available for the authenticated tenant. No sibling tool touches quota/allowance, so the resource is unambiguous and an agent can route to it 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?

Opens with an explicit trigger: 'Use this when the user asks how much managed execution allowance is reserved, consumed or still available.' It also gives the conditional branch for the unlimitedExecutions case, so the agent knows both when to call it and how to interpret the answer.

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 cover readOnlyHint, idempotentHint, and destructiveHint, so the read-only restatement is mild redundancy. The description adds non-annotation context: it returns the authenticated account identity, is scoped to only its own enrolled devices, and does not reserve quota — the last point being useful operational information an agent cannot get from the annotations.

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

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

Two sentences, front-loaded with the ordering instruction ('Use this first'), and every clause earns its place by covering return fields, scoping, and quota behavior.

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 parameters, no output schema, and full annotation coverage, the description supplies everything needed: when to call it, what it returns (devices, online status, workspaces, account identity), and its scope limits. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool takes no parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The description's notes on return scope implicitly explain why no filtering arguments exist.

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 — listing the user's paired Windows devices, their online state, and approved workspaces — and clarifies this is a discovery step rather than an execution step. An agent can distinguish it from execution_session_open and the fs_/git_ siblings without inspecting 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 explicitly says 'Use this first, before execution_session_open,' giving both the ordering constraint and the alternative it precedes. Nothing about when to reach for this tool is left to inference.

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