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

With no annotations, the description must carry the behavioral burden; it does disclose the restricted environment and that symlink traversal is blocked, which is useful safety behavior. It does not mention failure modes, what happens when the directory already exists, or whether parent directories are created, leaving some behavioral gaps.

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

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

The description is a single, front-loaded sentence with no filler. The main action appears first, followed by two concise, information-bearing constraints.

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

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

The tool is simple and has an output schema, so return-value documentation is not required here; the description covers the key permission and symlink constraints. It is still missing path-resolution details and error behavior, which an agent would need to invoke the tool with confidence.

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

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

Schema description coverage is 0%, so the description must compensate, but it only loosely maps 'directory path' to the path parameter and 'project/worktree' to the project parameter. It does not explain whether path is relative or absolute, how nested paths are handled, or what form a valid project identifier takes.

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—creating a directory path—and adds scoping constraints (write-enabled, non-protected project/worktree, symlink traversal blocked). It is clearly distinct from file-level and listing siblings, though it does not explicitly name an alternative tool.

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

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

The 'only in a write-enabled non-protected project/worktree' phrase gives an explicit precondition for safe use, which helps the agent decide whether this tool is applicable. It does not explicitly name alternatives or say when not to use it beyond that precondition.

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 burden of behavioral disclosure. It discloses the important guarantees: file is UTF-8, project must be write-enabled, and existing files are never overwritten. It does not describe failure behavior on collision, but the no-overwrite statement is a strong safety signal.

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

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

Two tight sentences with no redundancy. The primary action is front-loaded and the critical non-overwrite behavior is stated clearly and economically.

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

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

For a simple creation tool with an output schema, this is nearly complete: it covers the precondition (write-enabled project), the encoding, and the key side effect (never overwrites). It could add what happens if the file already exists, but the essential context for safe invocation 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 0%, and the description does not explicitly explain project, path, or content. However, the parameter names are intuitive and the phrase 'new UTF-8 file in a write-enabled project' adds useful context about what is being created. This is adequate but not exceptional.

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

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

The description uses a specific verb ('Create') and resource ('new UTF-8 file') with a clear scope ('in a write-enabled project'). The phrase 'never overwritten' disambiguates it from modification tools like replace_text and from directory creation.

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

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

It clearly implies this is for creating new files only, and the 'write-enabled project' condition plus 'never overwritten' give the agent useful constraints. It does not explicitly name alternatives such as replace_text for existing files, but the usage context is still clear.

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

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

With no annotations, the description must carry the behavioral burden. It discloses that deletion is conditional on an exact current SHA-256 match, which is a meaningful safety behavior beyond the raw schema. It does not detail mismatch errors or irreversibility, but 'Delete' plus the hash gate gives solid transparency.

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

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

The description is a single, front-loaded sentence with no filler. It communicates the action, scope, and key precondition efficiently.

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

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

The tool has three required parameters, no annotations, and zero schema field descriptions. The description fails to explain `project` and `path` and does not cover what happens when the SHA-256 check fails, leaving important invocation details 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%, and the description does not mention the `project`, `path`, or `expectedSha256` parameter names. It only gestures at the SHA-256 concept, leaving `project` and `path` semantics almost entirely 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?

The description states a specific verb ('Delete'), a specific resource ('one existing file'), and a distinguishing condition ('only when the caller supplies its exact current SHA-256'). This clearly separates it from file modification and creation tools in the sibling list.

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

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

The phrase 'only when the caller supplies its exact current SHA-256' gives explicit usage context and a precondition for safe invocation. It does not name alternative tools or exclusion cases, but the safety condition clearly implies when this tool should and should not be used.

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 clearly states the successful behavior—returning size and SHA-256—but does not disclose what happens for missing files, non-text files, invalid project names, or path interpretation. This is adequate but leaves meaningful gaps.

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

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

The description is a single focused sentence with no wasted words. It front-loads the action and output, making it instantly scannable for an agent.

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

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

The tool is simple and has an output schema, which covers return values. However, the lack of parameter semantics and minimal usage guidance means the description alone is not fully sufficient for an agent to confidently and correctly invoke the tool in all cases.

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

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

Schema description coverage is 0%, and the description does not explain the semantics, format, or relationship of 'project' and 'path'. It merely says 'an existing text file', which hints at path, but project remains unspecified. The description fails to compensate for the missing schema descriptions.

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

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

The description states a specific verb ('Return'), a precise resource ('an existing text file'), and exact output ('size and SHA-256'). This distinguishes it clearly from sibling tools like read_file, which return content, and list_directory, which lists files.

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 'existing text file' implies when the tool is applicable: only for files that already exist and are text files. However, the description does not explicitly state when to prefer this tool over alternatives such as read_file or find_files, nor does it mention exclusions or conditions beyond existence.

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 burden of behavioral disclosure. It clearly discloses recursive traversal, substring matching, and important exclusions like symlinks and dependency/build directories. It does not describe output shape or result limits, but the presence of an output schema reduces the need for that detail. The main behavioral traits are transparently stated.

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 packs in the core resource, matching criterion, recursion behavior, and traversal exclusions. There is no filler or repetition. Every phrase earns its place.

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

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

The description is adequate for a simple search tool and the output schema covers return structure. However, with no annotations and no parameter descriptions in the schema, the definition lacks enough detail for an agent to fully understand parameter semantics or to be confident about when to choose this over content-search and directory-listing siblings. It is complete enough to be usable but has clear gaps.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It does clarify that matching is by name substring, which maps to nameContains, and it mentions traversal behavior. However, it does not add meaning for the required 'project' parameter, the 'path' default/scope, or 'maxResults' bounds. With four parameters and no schema descriptions, this is a significant 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 identifies a specific action ('find files/directories') with a clear filtering criterion ('by name substring'). It also distinguishes itself from content-search siblings by emphasizing name-based matching, and from list_directory by stating recursion. This is a specific verb+resource description that an agent can separate from the sibling tools.

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

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

The description gives clear context: use this tool when you need recursive filename/substring lookup rather than content search or directory listing. It also states traversal exclusions, including sensitive paths and dependency/build directories. However, it does not explicitly name alternative tools such as search_text or list_directory, so the when-not-to-use guidance is implied rather than explicit.

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

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

With no annotations, the description must carry the behavioral burden. 'List' conveys a non-mutating read operation and 'local' clarifies scope, which is useful. However, it does not disclose prerequisites, error behavior, or output details such as how the current branch is indicated.

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

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

The description is one short sentence that front-loads the action and resource. Every word earns its place, with no filler or redundant restatement.

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

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

For a one-parameter tool with an output schema, the description captures the main behavior but omits what 'project' refers to and any usage or precondition context. An agent could infer much from the name and siblings, but the definition alone lacks full standalone guidance.

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 0%, and the description never mentions the required 'project' parameter. The parameter name and sibling tools like list_projects provide some context, but the description itself adds no meaning beyond the schema's type and required flag.

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

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

The description states a specific verb ('List'), a specific resource ('local Git branches'), and the added detail that the current branch is also reported. This clearly distinguishes it from sibling operations like git_create_branch or git_status.

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

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

The description gives no explicit guidance about when to call this tool versus alternatives, nor does it state conditions such as needing a valid Git-initialized project. The only usage signal is the verb 'List', which implies a read-only branch inspection task, but that is left to inference.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It discloses important traits: staging and committing only non-sensitive changes, disabled hooks and GPG signing, and the absence of push. Some ambiguity remains about how 'non-sensitive' is determined or what happens when sensitive changes are present.

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 dense sentence with no filler. It front-loads the core action and packs the key constraints, disabled features, and limitation into a compact, readable structure.

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

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

The description covers the purpose, writable-worktree requirement, sensitive-change limitation, disabled hooks/signing, and the no-push constraint. The main gap is that 'non-sensitive' is not precisely defined, which could matter for a commit operation.

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

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

Schema description coverage is 0%, and the description does not explain the 'project' or 'message' parameters. The parameter names are somewhat self-evident, but the description fails to compensate for the complete lack of schema-level 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?

States a specific verb and resource: 'Stage and commit only non-sensitive changes in a writable runner-managed mcp/* worktree.' It clearly identifies what the tool does and is easily distinguished from sibling inspect/branch/worktree tools.

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

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

Gives explicit usage conditions: only writable runner-managed mcp/* worktrees, only non-sensitive changes, and no push available. It does not name an alternative tool, but the boundaries of appropriate use are clear from the constraints.

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 burden of disclosing side effects; it usefully states that the tool does not check out the branch and imposes naming safety restrictions. However, it does not mention failure behavior, permissions, or how baseRef affects the created branch.

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 states the action, the restriction, and the key non-checkout behavior with no redundant words. The content is compact and immediately scannable.

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

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

For a tool with three parameters and no annotation or schema descriptions, the description covers only branch naming. It omits project identification and baseRef semantics, and does not reference the output schema or alternative tools, leaving important invocation details unstated.

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 explain parameters; it only clarifies the branch naming rule. 'project' and 'baseRef' are left undefined, leaving agents to infer meaning from names and defaults alone.

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

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

The description states a specific action ('Create'), a constrained resource ('an mcp/* branch'), and a distinguishing side-effect ('without checking it out'). The naming restriction and title differentiate it from branch listing or checkout tools.

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

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

The description makes the intended use clear: create branches only under the mcp/* prefix and not on main/master. It explicitly excludes arbitrary branch names, though it does not name alternative sibling tools such as git_worktree_create or git_branch_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?

No annotations are provided, so the description carries the behavioral disclosure burden. It does disclose two important traits: the diff is 'bounded' and sensitive files are excluded. However, it leaves those terms undefined and does not mention read-only behavior, authentication needs, or error conditions.

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

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

Two concise sentences with no filler. The main safety behavior is front-loaded, and the supported modes are stated efficiently.

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

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

The description is adequate for a moderately complex tool with an output schema, but it leaves important invocation details unexplained, especially project/path semantics and what 'bounded' means. An agent could call the tool correctly for simple cases but would likely guess on parameter usage.

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 undocumented parameters. It hints at the roles of staged, baseRef, and headRef via the supported diff modes, but it does not explain the required 'project' parameter or the optional 'path' parameter, leaving a significant gap in parameter understanding.

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

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

The description uses a specific verb-resource pair ('Return ... diff') and clearly identifies the three supported modes: working-tree, staged, and ref-to-ref. This distinguishes it from sibling tools like git_status and git_log without ambiguity.

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

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

It states the concrete scenarios in which the tool is applicable (working-tree, staged, or ref-to-ref diffs), providing clear context for when to call it. It does not explicitly name excluded alternatives, but the mode enumeration is sufficient to route an agent away from status/log tools.

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

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

With no annotations provided, the description carries the full behavioral burden and does so well. It discloses idempotency, the ALREADY_EXISTS return behavior, and lists explicit non-actions, which are exactly the behavioral traits an agent needs to know before invoking a creation tool.

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 worded sentences with no filler. The main purpose is front-loaded, followed by high-value idempotency and non-side-effect information. Every sentence earns its place.

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

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

For a creation tool with full schema coverage and an output schema, the description is complete. It covers scope, visibility, idempotency, and what the operation will and will not do, giving an agent everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds 'allowlisted' and 'public or private' context, but these largely repeat existing schema descriptions. Baseline 3 is appropriate since the schema carries the parameter documentation weight.

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

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

The description clearly states the specific operation: creating a new repository under an allowlisted GitHub organization. It also names the key constraint (visibility) and implicitly differentiates itself from sibling tools like github_repository_info by being the creation tool.

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

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

The description gives clear context about what the tool does and what it deliberately does not do (no README/license/gitignore, no pushing code, no configuring remotes). It does not explicitly name sibling alternatives, but its scoping and negative behaviors effectively guide when 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?

With no annotations provided, the description carries the full behavioral burden. It clearly frames the operation as a read-only metadata query and discloses the key result categories including existence, owner, visibility, default branch, fork/archived status, and URL. The 'allowlisted organization' phrasing also signals an access constraint, though failure behavior is not explicitly covered.

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

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

The description is a single efficient sentence that front-loads the operational purpose and follows with the concrete metadata fields returned. Every phrase earns its place; there is no redundancy.

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

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

The tool is simple with only two required parameters, the schema covers both, and an output schema is indicated. The description supplies the essential behavioral framing and return-value summary, so an agent has enough context to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds useful context about the allowlisted organization and the kind of metadata returned, but does not materially enhance parameter-level meaning beyond the schema.

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

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

The description states a specific verb ('Query metadata'), a specific resource ('a GitHub repository'), and a scope ('under an allowlisted organization'). It also enumerates the returned fields, clearly distinguishing it from github_repository_create and other file/project tools.

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

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

The intended use is inferable from 'Query metadata' and the sibling github_repository_create, but the description does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or alternative-tool routing are provided.

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

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

With no annotations, the description must carry the safety burden. 'Return' clearly signals a read-only operation and 'safe path' hints at path restrictions, but 'safe' is undefined and there is no mention of permissions, failure modes, or what exactly 'safe' means in this context.

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

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

One sentence, no filler, and the key purpose is front-loaded. It is appropriately concise for a simple read-only log 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?

The description is too terse relative to a 0%-coverage schema and absent annotations. It fails to mention the required `project` parameter, the `limit` behavior, or clarify the vague 'safe path' constraint. The output schema helps with return structure but does not compensate for these input-side 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. It only alludes to the optional path parameter via 'scoped to one safe path'; the required `project` parameter and the `limit` parameter are not explained at all.

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

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

The description uses a specific verb ('Return') and resource ('recent commit metadata'), making the core purpose clear. It does not explicitly distinguish itself from siblings like git_status or git_diff, but the commit-history focus is evident from the name and object.

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: use this tool to inspect recent commit metadata, optionally filtered by path. It does not explicitly say when to prefer this over git_status, git_diff, or git_branch_list, nor does it provide exclusions or alternative routing.

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

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

There are no annotations, so the description must carry the behavioral burden. It discloses one useful trait — the output omits sensitive-path entries — but it does not state whether the operation is read-only, what 'safe' means beyond that omission, or how errors or invalid projects are handled.

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

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

The description is a single concise sentence with no filler, and the main action is front-loaded. It is efficient but slightly underspecified in ways that other dimensions capture.

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

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

Given the tool's low complexity and the presence of an output schema, the core behavior is conveyed adequately. However, with no annotations and no parameter or usage guidance, an agent still has to infer what 'project' should be and when this tool should be preferred over sibling Git tools.

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

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

Schema description coverage is 0%, and the description does not mention the required 'project' parameter at all. The name and minLength hint that it identifies a project, but the description adds no meaning beyond what the schema already minimally conveys.

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

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

The description clearly identifies the core operation as returning Git status, with a distinguishing qualifier: it omits sensitive-path entries. This differentiates it from related Git tools like git_diff and git_log, though the terms 'safe' and 'sensitive-path' are left somewhat undefined.

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

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

No guidance is provided on when to use this tool versus the sibling Git tools. It does not mention that it is a read-only status command, nor does it point to git_diff or git_log for changes or history.

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 behavioral disclosure burden. It reveals useful behavior: worktrees are isolated, writable, created under the runner worktree directory, and branches use an mcp/* namespace. However, it does not explain side effects, idempotency, failure conditions, or whether baseRef affects branch creation.

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

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

The description is a single, dense sentence with no filler and front-loads the core action. It could be slightly clearer by separating 'create' from 'register', but it remains appropriately compact.

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?

Although an output schema exists, the description is incomplete for a 3-parameter tool with 0% schema description coverage and no annotations. It omits baseRef semantics, project meaning, failure behavior, and whether the branch must not already exist. The provided context is a useful start but not sufficient for correct invocation in edge cases.

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 0%, and the description compensates only partially. It hints at the branch parameter via 'mcp/* branch' and at the project worktree location, but says nothing about baseRef or the exact meaning of project. Two parameters remain essentially undocumented in both schema and 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 action ('Create/register an isolated writable worktree') and a concrete resource ('on an mcp/* branch under the runner worktree directory'). It clearly distinguishes this tool from siblings like git_worktree_remove and git_create_branch by scope and location.

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 phrasing implies this tool is used when an isolated writable worktree is needed, but it does not explicitly state when to use it over alternatives, when not to use it, or how it relates to siblings like git_create_branch. Usage context is present but only by 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?

With no annotations, the description carries the full burden and does a good job: it discloses the dirty-worktree refusal, the retention of the branch, and the unregistration step. It does not describe error behavior or the exact meaning of 'unregister', but the behavior most relevant to avoiding destructive mistakes is present.

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

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

The description is two tight sentences that front-load the action and then add necessary constraints. Every part adds information, and there is no repetition of the title or schema.

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

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

The tool is simple and the output schema exists, so return-value documentation is not required. The main missing piece is parameter semantics: 'project' is ambiguous. The behavioral constraints are well covered, but the single required input remains under-specified.

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

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

The schema provides only 'project' as a required string with minLength 1 and no description. The tool description gives zero additional meaning for this parameter, so an agent cannot tell whether 'project' is a worktree path, a project name, a directory, or an identifier. With 0% schema description coverage, this is a notable 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 uses a specific verb and resource: 'Remove a clean runner-managed worktree and unregister it.' This clearly distinguishes the tool from siblings like git_worktree_create and from branch-deletion operations by adding scope and constraints ('runner-managed', 'branch is retained').

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

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

The description gives clear usage conditions: only clean worktrees can be removed, dirty worktrees are refused, and the branch is retained. This implies when-not-to-use, but it does not explicitly name alternatives or state when another tool like git_create_branch or manual git worktree removal should be preferred.

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?

There are no annotations, so the description carries the behavioral disclosure burden. It meaningfully discloses that sensitive paths are hidden and that the operation is scoped to one directory inside a registered project. It does not mention error behavior or permissions, but the non-mutating nature is clear from the verb 'List.'

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

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

The description is a single concise sentence that front-loads the action and resource. Every phrase adds value: the scope ('one directory'), the context ('inside a registered project'), and the filtering behavior ('hiding sensitive paths').

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

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

The tool is simple and an output schema exists, so return value documentation is not needed. However, the description does not fully clarify path semantics or provide explicit guidance on when to prefer this tool over find_files or read_file. It is minimally viable but leaves clear gaps for an agent deciding among siblings.

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

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

Schema description coverage is 0%, so the description must compensate. It provides some semantic anchoring: 'registered project' maps to the project parameter and 'one directory' hints at the path parameter. However, it does not explain whether path is relative to the project root, what format project takes, or the meaning of the '.' default, leaving partial ambiguity.

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

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

The description states a specific verb and resource: 'List one directory inside a registered project.' The phrase 'while hiding sensitive paths' further defines scope. This makes it clear that the tool returns directory entries for a single directory and differentiates it from sibling tools like list_projects, find_files, and read_file.

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

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

The description implies usage: it is for listing a single directory within a registered project, not for recursive search or reading file contents. However, it never explicitly names alternatives or states when not to use this tool, so the guidance is only implicit.

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

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

There are no annotations, so the description carries the transparency burden. It clearly indicates a non-mutating enumeration operation, scopes the source ('registered with the local MCP runner'), and states that access mode is part of the result. This is adequate for a simple no-parameter list tool, though it does not mention edge cases or read-only guarantees explicitly.

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

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

The description is one tight sentence that front-loads the action and resource, then adds the relevant output detail. No filler or repetition; every word contributes.

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

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

For a zero-parameter, no-annotation listing tool with an output schema present, the description provides enough context: what is listed, where it is listed from, and what aspect of each project is included. No critical information is missing for correct invocation.

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

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

The input schema has zero parameters and 100% schema coverage, so there is nothing for the description to add about parameter meanings. The baseline for zero-parameter tools is 4, and the description sufficiently describes what the tool returns instead.

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

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

The description uses a specific verb ('List') and a specific resource ('projects registered with the local MCP runner'), and adds the distinguishing detail that access mode is included. This clearly separates it from sibling tools like project_info, which likely targets a single project.

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

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

The intended use is clear: call this when you need to enumerate registered projects and their access modes. It does not explicitly name alternatives or state when not to use it, but with zero parameters and a straightforward list purpose, the usage context is evident.

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 explicitly signals a read-only operation with 'Return' and lists all the state it exposes, making the non-mutating nature clear. It does not describe error cases or the meaning of 'access mode,' but for a simple info query the behavior is adequately disclosed.

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

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

The description is one tight sentence, front-loaded with the action and a compact enumeration of returned data. Every word contributes to the meaning, with no fluff 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?

An output schema exists to detail return shape, and the description covers the high-level output categories. However, the input parameter is left underspecified and there is no pointer to sibling tools like list_projects that could provide a valid value. For a single-parameter tool this is a moderate but real gap.

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

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

Schema description coverage is 0%, and the description does not clarify what value 'project' should take (name, ID, path) or how to obtain it. The parameter name and the phrase 'project root' offer only an implicit hint, so the description does not compensate for the missing schema documentation.

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

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

The description states a specific verb ('Return') and enumerates the exact resource-level data returned: project root, access mode, managed-worktree metadata, and Git branch state. This clearly identifies it as a per-project info tool and distinguishes it from siblings like list_projects or git_status without ambiguity.

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

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

There is no guidance about when to use this tool versus alternatives such as list_projects, file_info, or git_status. The description implies it is for retrieving a single project's details, but it gives no prerequisites, routing conditions, or exclusions.

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

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

With no annotations, the description carries the burden and it does add useful behavioral context by explaining the difference between executionSupported and executionEnabled, including the kill switch. The read-only nature is reasonably clear from 'List', though it is not explicitly stated.

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

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

The description is compact and front-loaded: the first sentence states the core action, and the second sentence defines the two execution flags. No unnecessary words or repetition.

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

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

The output schema likely covers return shape, and the description explains the two boolean fields well. However, the project parameter remains underspecified, and there is no explicit connection to run_script for the agent to understand the full workflow context.

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

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

Schema description coverage is 0%, and the only required parameter 'project' is not explained. The description says 'for this project' but does not clarify whether the value should be a name, ID, or path, so it fails to compensate for the missing schema documentation.

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

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

The description clearly states the action and resource: list package.json scripts and report execution support for the project. It distinguishes itself from the sibling run_script tool by describing listing and capability reporting rather than execution.

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

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

The description implies this is a pre-flight inspection tool for script execution, but it does not explicitly say when to use this tool versus run_script or other siblings. No alternatives or exclusions are mentioned.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It does disclose that the operation is a non-mutating read of exactly one UTF-8 text file within a registered project. However, it does not mention path resolution, error behavior, or access prerequisites beyond 'registered project'.

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

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

The description is a single, front-loaded sentence with no filler or repetition. Every word adds meaning: 'Read', 'one', 'UTF-8 text file', and 'inside a registered project' are all relevant to invoking the tool correctly.

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

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

For a simple tool with two required string parameters and an output schema, the description covers the core operation and scope adequately. The main gap is the absence of routing guidance among the many file-related siblings, but the low complexity and existing output schema keep the definition reasonably complete.

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

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

The input schema provides only minLength constraints with 0% description coverage. The description adds limited semantics by implying that 'path' refers to a text file and that 'project' must be a registered project, but it does not clarify path format, whether paths are relative or absolute, or what values are valid for project.

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

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

The description clearly states a specific verb ('Read'), a specific resource ('one UTF-8 text file'), and a scope ('inside a registered project'). The singular 'one' helps distinguish it from the sibling tool 'read_files', so an agent can tell them apart.

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

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

The description provides no guidance on when to use this tool versus alternatives such as 'read_files', 'list_directory', 'find_files', or 'file_info'. It does not mention exclusions, prerequisites, or why an agent would choose this tool over its siblings.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose that the operation is a read, limits file count to 20, restricts to UTF-8 text, and scopes to one registered project. However, it does not explain behavior for missing files, binary/non-UTF-8 content, path resolution, or error cases, so transparency is incomplete.

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

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

The description is a single sentence with no filler. Key constraints—20 files, UTF-8, one registered project—are front-loaded, and every phrase earns its place.

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

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

For a simple two-parameter read tool with an output schema, the basic call shape is inferable. But with no annotations and no schema descriptions for the parameters, the agent still lacks important details about path and project identifiers and error handling, leaving meaningful gaps for correct invocation.

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

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

Schema description coverage is 0%, and the description only loosely maps 'files' to the paths parameter and 'registered project' to the project parameter. It does not specify whether paths are relative or absolute, whether project is a name or ID, or any format constraints, so it adds minimal meaning beyond the parameter names.

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

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

The description uses the specific verb 'Read' with a clear resource: up to 20 UTF-8 text files from one registered project. The plural 'files' and the 'up to 20' limit distinguish it from the sibling single-file tool read_file, and the title reinforces the same distinction.

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 clear context—read multiple UTF-8 text files from a single registered project—but it never explicitly names an alternative or states when not to use this tool. The guidance is implied via the plural and 'up to 20' rather than stated 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?

With no annotations, the description carries the behavioral burden. It does disclose that the operation mutates an existing file, is limited to one text block, and is guarded by expectedSha256, which is meaningful context. However, it does not state failure behavior for hash mismatch, missing oldText, or multiple occurrences, nor any permission or side-effect details.

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

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

The entire description is one efficient sentence with no filler. The primary action and the distinguishing concurrency guard are front-loaded, and every word contributes useful 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?

Given no annotations, zero schema parameter descriptions, and a mutation tool requiring a SHA-256 guard, this description is too thin. The agent still needs to know how to obtain expectedSha256, what error cases exist, and what project/path refer to. The output schema may cover return values, but it does not compensate for the missing operational guidance.

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. It adds some meaning for expectedSha256 ('concurrency guard') and implies oldText/newText roles, but project and path are left undefined, and no parameter mapping is provided. This is insufficient for five required 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 names a specific action ('Replace'), a specific resource ('text block in an existing file'), and key constraints ('exactly one', 'expected SHA-256 concurrency guard'). This clearly distinguishes it from sibling tools like create_file, delete_file, or search_text.

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

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

The description implies usage for single targeted replacements rather than whole-file writes or multi-occurrence edits, but it never explicitly states when to use this tool versus alternatives. No sibling tool is named and no exclusion criteria are provided, so the agent must infer the boundary from the phrase 'exactly one text block'.

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 provided, the description carries the full burden and does well: it discloses that network is always 'none', execution is confined to a runner-managed READ_WRITE mcp/* worktree, and a non-zero exit code is still a successful MCP call. These are non-obvious and valuable operational details. It omits a few edge behaviors, but the output schema covers return shape.

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, no filler. The most important behavioral constraints are front-loaded, and the surprising exit-code semantics are given their own sentence. Every clause adds decision-relevant 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 5-parameter tool with no annotations and no schema descriptions, the description is not fully complete: it lacks parameter-level guidance and explicit routing to project_scripts. However, it does cover environment, network, and exit-code semantics, which are the riskiest aspects of invoking this tool, and an output schema exists for return-value expectations.

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

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

Schema description coverage is 0%, so the description must compensate, but it only indirectly touches parameters: 'network is always none' clarifies the network parameter, and 'hash-pinned' hints at expectedPackageSha256. It does not explain project, script, timeoutSeconds, or expectedPackageSha256 beyond what the bare schema shows.

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

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

The description states a specific action and resource: 'Execute an allowlisted, hash-pinned npm/pnpm script inside a macOS Seatbelt sandbox.' It clearly differentiates run_script from file/git tools and from project_scripts, which likely lists scripts rather than executing them.

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

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

The tool's purpose implies it should be used when a project-defined npm/pnpm script needs to be executed, and the sandbox/network constraints set clear expectations. However, it does not explicitly say when to prefer this over alternatives, nor does it mention project_scripts as the way to discover available allowlisted scripts or what happens for non-allowlisted scripts.

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 provided, the description carries the full burden, and it spends it well: it discloses that matching is literal, results are capped ('bounded output'), and — critically — that regex and shell execution are explicitly not used, preventing dangerous assumptions about ReDoS or command injection. It omits recursion scope and binary/hidden file handling, but the most safety-relevant boundaries are stated.

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 where every clause earns its place: the action comes first, then the output-bounding constraint, then the two safety exclusions. There is no filler and no repetition of schema defaults like maxResults=100 or caseSensitive=false.

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

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

The output schema exists, so return values need not be explained, and the description covers the core invocation-safe facts. However, with 5 parameters, 0% schema coverage, and zero annotations, the absence of any guidance on search scope (recursion, how path interacts with project) and no sibling routing leaves the agent with adequate-but-gappy information.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning for query ('fixed text string' = literal, not regex) and maxResults ('bounded output'), but provides nothing for project, path, or caseSensitive, which must be inferred from parameter names alone. That is partial compensation for a significant 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 uses a specific verb and resource — 'Search for a fixed text string in project files' — and adds two scoping constraints ('fixed text string', 'bounded output'). These constraints distinguish it from siblings like find_files (filename search), replace_text (text mutation), and run_script (shell execution) without needing to open the schema.

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

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

The exclusions 'regex and shell execution are not used' imply when NOT to use this tool, but the description never names the alternative to prefer for regex or shell-based search (e.g., run_script, grep-style tools). Usage context is implied rather than explicit, so the agent must infer routing from sibling tool names.

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