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

With no annotations, the description carries the full burden. It discloses meaningful search behavior: exact-fragment matching, UTF-8 file scope, and automatic exclusion of generated/vendor directories and sensitive files. It does not mention matching semantics or result behavior, but the stated exclusions are valuable behavioral context beyond a generic 'search' claim.

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 the action, target, and key exclusions without filler. Every phrase contributes information an agent needs for selection and invocation.

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

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

For a three-parameter read-only search tool, the description is nearly complete: it defines the query type, applicable file set, and ignored paths, and the schema covers ID format and result limits. It omits return-format details and what counts as 'sensitive files,' but no output schema exists and those gaps are not critical for invoking the tool.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies the query parameter semantics ('exact text fragment') and the file scope, but it does not explain projectId or maxResults beyond what their names and schema constraints already imply. The compensation is partial, not comprehensive.

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 ('Search'), a resource ('UTF-8 project files'), and a precise matching mode ('exact text fragment'), which clearly conveys what the tool does. It does not explicitly contrast itself with sibling tools like file_read or git_diff, but the 'project files' and 'exact text fragment' wording makes its purpose distinguishable.

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

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

The description implies the intended use case (finding an exact text occurrence in a project) and scopes it to UTF-8 files while excluding generated/vendor and sensitive files. It provides no explicit 'when to use this vs. alternatives' guidance, so an agent must infer the selection from tool names.

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 full behavioral disclosure burden. It discloses two useful behaviors: results are bounded and sensitive files are hidden. It does not mention output format, error behavior, path validation, or whether hidden files are silently omitted, so transparency is only partial.

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 tightly written sentence with no filler. It front-loads the verb and object, and the qualifiers 'bounded' and 'hiding sensitive files' add meaningful value rather than wasted words.

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 three parameters, zero schema description coverage, no annotations, and no output schema, the single sentence is not enough. An agent cannot tell how path and maxDepth interact, what a bounded tree looks like in the response, or how projectId maps to a registered workspace.

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 needed to compensate by explaining projectId, path, and maxDepth. It does not explain any of them; 'bounded' only vaguely alludes to maxDepth. All parameter meaning falls back to names and schema constraints, which is insufficient.

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 operation: list a bounded directory tree inside a registered workspace. It also adds the distinguishing behavior of hiding sensitive files, which separates it from content-focused siblings like file_read, file_write, and code_search. This is clear and actionable.

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 'inside a registered workspace' gives contextual placement, and 'bounded directory tree' implies use for structural exploration rather than file content access. However, it does not name alternatives or explicitly state when not to use this tool, so usage guidance is mostly 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?

No annotations are provided, so the description carries the full burden. It discloses the matching behavior, the failure conditions for missing or ambiguous matches, and UTF-8 encoding. However, it does not mention side effects beyond replacement, such as whether the file is modified in place, whether permissions are needed, or what happens on success.

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

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

The description is a single, tightly packed sentence with no filler. It front-loads the core operation and includes the most important constraints and failure behavior 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 basic selection and invocation, but with no output schema and no annotations, an agent still lacks information about return values, whether oldText must be unique or can be a substring, and what constitutes success. The failure cases are covered, but the overall operational context is incomplete for a mutating 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 0%, so the description must compensate for the four parameters. It partially clarifies oldText/newText via 'matching text block' and 'Replace', but it does not explain projectId or path meaning, path scope, or the relationship between the parameters beyond the basic replace concept.

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 ('Replace'), a specific resource ('one matching text block in a UTF-8 project file'), and adds distinguishing constraints ('exactly one', fails on missing/ambiguous matches). This clearly differentiates file_patch from file_write and file_read.

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

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

The description clearly implies when to use this tool: when an exact, unique text replacement is needed in a project file. It does not explicitly name alternatives such as file_write for whole-file writes, but the 'exactly one matching text block' phrasing gives clear contextual guidance and the failure conditions reinforce the intended use.

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

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

With no annotations, the description carries the behavioral disclosure burden. It usefully discloses that traversal, symlink escapes, sensitive files, and secret patterns are guarded. However, 'guarded' is ambiguous—it does not specify whether such attempts result in an error, redaction, or empty content—and there is no mention of behavior for missing files or non-UTF-8 content.

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 short sentences with no filler. The core action is front-loaded, and the security guardrails are stated compactly without redundant elaboration.

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

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

For a two-parameter read tool, the description covers basic purpose and safety constraints, and the schema covers parameter types. Still, it omits behavior for guarded cases, errors, and return value shape, which an agent would need to fully predict invocation outcomes. It is adequate but not complete.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning by implying projectId identifies a registered workspace and path refers to a file path within it. However, it does not clarify path format, whether paths are relative or absolute, or how projectId maps to the workspace beyond general inference.

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 ('Read'), a resource ('a UTF-8 file'), and a clear scope ('inside a registered workspace'). It is easily distinguished from siblings like file_write and file_patch, which are mutations, and from directory_tree or code_search, which serve different read purposes.

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 'inside a registered workspace' implies the tool requires a valid projectId and is meant for reading files within that boundary. However, it does not explicitly say when to prefer this over directory_tree or code_search, nor does it state when not to use it, leaving usage guidance 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 provided, the description carries the full burden. It discloses destructive behavior ('replace'), the encoding contract ('UTF-8'), and important safety behavior ('Sensitive paths and symlink targets are rejected'). It omits some details like permission requirements and return values, but the key side effects are transparent.

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

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

Two sentences with no filler. The core function is front-loaded, and the safety constraint is presented as a separate, easy-to-parse sentence.

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 write tool with no annotations, no output schema, and no schema-level parameter descriptions, the description is under-specified. An agent cannot tell what a successful call returns, how paths are resolved inside the workspace, or what qualifies as a 'sensitive path.' The basic operation is clear, but the operational context for reliable invocation is 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%, so the description needed to add meaning to the parameters. It only indirectly covers them: 'registered workspace' implies projectId, 'UTF-8' relates to content, and path constraints are mentioned as sensitive/symlink rejections. It does not explain whether path is relative to the workspace root, whether directories are created, or how the 5MB content limit behaves.

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 object: 'Create or replace one UTF-8 file inside a registered workspace.' This distinguishes file_write from siblings like file_read, file_patch, and workspace-management tools by making full-file write/replace semantics explicit.

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 clear implied context: use this tool to create or replace full files in a registered workspace. However, it does not explicitly say when to prefer file_patch for partial edits or how to handle an unregistered workspace, so guidance is implied rather than made 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 carries the behavioral burden. It explicitly says 'non-mutating', which is a critical safety trait for this read-only operation. However, it does not disclose output format, error behavior for an unregistered project, or how the staged flag affects which changes are diffed.

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

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

The description is a single front-loaded sentence with no filler. Every word earns its place, and the most important qualifier, 'non-mutating', appears before the resource name.

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

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

For a tool with two parameters, no annotations, and no output schema, this one-sentence description is minimally callable but incomplete. It lacks staged semantics, return-value expectations, and any relationship to git_status, so an agent must rely on background git knowledge to fill 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 the parameters. It adds that projectId must refer to a registered project, but it says nothing about the staged parameter, leaving the agent to infer its meaning from the boolean name and default.

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 ('Run') and resource ('git diff'), scoped to a registered project, and the 'non-mutating' qualifier distinguishes it from mutating sibling tools like file_patch. An agent can clearly tell this is the diff tool and not git_status just from the wording.

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

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

No when-to-use or when-not-to-use guidance is provided. The sibling git_status is not mentioned, so the description does not help an agent choose between git_diff and git_status; the only contextual clue is the registered-project scope.

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 discloses that the tool does not invoke a shell, which is a meaningful execution trait, and specifies the short-format status output. It does not detail error behavior, but git status is a standard read-only operation and the command itself implies its behavior.

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

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

A single, front-loaded sentence states the action, scope, and a key behavioral distinction with no wasted words. It is concise without losing necessary 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 one-parameter read-only Git status tool, the description plus schema is nearly sufficient for correct invocation. It lacks explicit return-format details and error handling, but '--short' already communicates the expected output style and the schema supplies the only required input.

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 has 0% description coverage, so the description must provide parameter meaning. It supplies the semantic anchor 'inside a registered project,' which maps to projectId, but it does not explicitly state that projectId is the identifier of the registered project or explain the UUID constraint. With only one parameter, the mapping is still inferable.

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 command and resource: 'Run git status --short inside a registered project.' This clearly states what the tool does and distinguishes it from related tools like git_diff or process_run.

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 usage context: the command must run inside a registered project, and the tool is specifically a shell-free way to get git status. It does not explicitly name alternative tools or when not to use it, but the context is sufficient for an agent to choose it over running a shell 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 no annotations provided, the description carries the full transparency burden. It usefully discloses that execution bypasses the shell, that only explicitly allowlisted executables are permitted, and that the tool is disabled by default until configuration. It does not describe output behavior or side effects, but the security-relevant traits are well 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?

Two tight sentences with no filler. The core behavior is front-loaded, and the important operational constraint (disabled until configured) is placed at the end without 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?

Given the tool's moderate complexity, the description covers the essential execution model, allowlist constraint, and configuration prerequisite. It lacks an explicit mention of return values or error behavior, and with no output schema the description could have added a bit more, but the critical calling context 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%, so the description must compensate for the four parameters. It explains 'command' as an allowlisted executable and 'args' through 'using argv directly', but leaves 'projectId' and 'timeoutMs' completely unaddressed. This is a meaningful gap, especially for projectId which is required.

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 ('Run'), a specific resource ('one explicitly allowlisted executable in a project workspace'), and the execution mode ('using argv directly, no shell'). This clearly distinguishes process_run from sibling file, project, and git 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 provides clear usage context: it runs only allowlisted executables and is disabled by default until FORGEGUARD_COMMANDS is configured. It does not explicitly name alternative tools or state when not to use it, but the unique execution role makes the intended use fairly unambiguous.

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

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

No annotations are provided, so the description carries the full burden of disclosing behavior, but it only states 'Get one registered project by id.' It does not describe what happens when the projectId does not exist, whether 'registered' excludes certain projects, what fields the response contains, or any error behavior. For a tool with no annotations and no output schema, this is a notable transparency gap.

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

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

The description is a single, front-loaded sentence with no filler: 'Get one registered project by id.' Every word contributes to conveying the action, object, and scoping. This is an excellent example of concise, well-structured tool documentation.

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 get-by-id tool with one required parameter, the description is enough to invoke the tool, but the absence of an output schema and behavioral details leaves gaps about the return format and error handling. An agent would need to make assumptions about what 'project info' contains and how failures are signaled. It is a minimal viable description rather than a fully complete one.

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 0% description coverage, so the description must compensate. It does tie the single projectId parameter to the resource by saying 'by id,' and the schema already provides type, format, and pattern constraints. With only one self-explanatory parameter, this minimal linkage is adequate, though it could explicitly confirm that projectId refers to the registered project identifier.

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

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

The description uses a specific verb ('Get'), names the resource ('project'), and scopes it with 'one ... by id', which clearly differentiates it from the sibling project_list tool that presumably returns multiple projects. An agent can immediately understand this is a single-record lookup, not a listing or mutation operation.

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

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

The description gives no explicit guidance on when to use this tool versus alternative siblings such as project_list or project_register. The phrase 'by id' implies a use case, but there are no exclusions, prerequisites, or alternative routing directions provided, leaving the agent to infer the intended context.

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

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

With no annotations, the description carries the behavioral burden, but 'List' clearly conveys a non-mutating enumeration and the qualifier 'registered for this ForgeGuard process' defines the exact scope of the operation. It does not discuss output format or error cases, but for a zero-parameter read-only list tool the core behavior is sufficiently transparent.

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

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

The entire description is a single front-loaded sentence with no filler. Every word contributes semantic content: action, object, and scope.

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

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

For a no-parameter tool, the description covers the necessary context: what is being listed and for which process. It could optionally describe the shape of the returned list, but since no output schema exists and this is a simple enumeration, the description is largely 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 tool has zero parameters, so there is no parameter information for the description to add. The 100% schema coverage and empty properties object make the schema complete, satisfying the 0-param baseline of 4.

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 ('project workspaces registered for this ForgeGuard process'), making the tool's purpose unambiguous. The scope qualifier also distinguishes it from siblings such as project_register (creation) and project_info (single-item detail).

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 rather than stated: 'List project workspaces' suggests this is the tool for enumerating all registered workspaces, while project_info/project_register are likely for single-project detail or registration. However, the description provides no explicit when-to-use or when-not-to-use guidance, so it offers only indirect 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 carries the full burden of behavioral disclosure. It mentions a validation constraint (allowed root), but does not disclose what registration does, whether it is persistent, what side effects occur, or whether it fails if the project already exists.

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

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

The description is two concise sentences with no filler. It front-loads the core action and then adds the key constraint, making it easy for an agent to parse quickly.

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

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

For a tool with no annotations, no output schema, and no parameter descriptions, this description is under-specified. It omits what happens after registration, what the 'name' parameter controls, and how 'root' interacts with the allowed-root restriction.

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 references 'directory' and 'allowed root'. It does not meaningfully explain the required 'root' parameter or the optional 'name' parameter, their relationship, or expected formats.

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 ('Register') and a clear resource ('a project directory'), which clearly distinguishes this tool from the sibling read/utility tools like project_list and project_info. The required allowed-root constraint further clarifies the tool's scope.

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 clear context for usage by stating that the directory must be inside a locally configured allowed root. It does not explicitly name alternatives or when-not-to-use conditions, but the tool's purpose is distinct enough among the siblings that the context is sufficient.

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