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

With no annotations, the description carries the full burden and discloses the key side-effect traits: the operation is 'atomic,' 'additive and idempotent,' and never overwrites existing artifacts. It also covers the non-obvious merge behavior of `.project-bootstrap-questions.yaml` into the interview set. It stops short of stating permissions needed or the response contract, which matters for a multi-file scaffold, but the riskiest unknowns (overwrite behavior and artifact set) are explicitly resolved.

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 dense sentence front-loaded with the core verb and resource, then a colon-list of artifacts and em-dash side effects. Every clause adds a distinct behavioral fact (what's created, idempotency, YAML merge) with zero fluff. Slightly long, but the content density justifies the length for a multi-artifact operation.

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 4-parameter scaffold with nested objects, no annotations, and no output schema, the description covers purpose, artifact set, side-effect guarantees, and the custom-questions merge. The one gap is the return value: without an output schema, it never says what the tool returns (beyond the auto_reindex hint in the schema). That is minor given everything else is covered.

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 baseline is 3. The description adds value beyond the schema with the merge rule for `.project-bootstrap-questions.yaml` and the link between project_sections to get_bootstrap_questions answers, which affects which keys the agent must supply. That contextual enrichment justifies a 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?

Opens with a specific verb and resource — 'Atomically scaffold a brand-new .context/ directory' — then enumerates the exact artifacts created (decisions/, sessions/, two governance docs, project.md, ADR-00001). This scope cleanly distinguishes it from siblings like write_project (single file), create_adr (single ADR), and index_project_context (reindex only). An agent can tell this is the whole-project initializer without opening any sibling 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 condition 'for a project that doesn't have one yet' gives a clear when-to-use trigger, and the idempotency note ('artifacts that already exist are skipped, not overwritten') clarifies behavior when state is partial. It also references the prerequisite flow, tying interview answers to `get_bootstrap_questions`. It does not explicitly name sibling alternatives like write_project for updating existing projects, so exclusions are 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 of behavioral disclosure. It transparently discloses several key behaviors: allocation of the next sequential number, writing a stub with placeholder text, and the lack of lock/retry for concurrent creation. However, it does not mention the return value/response format or potential error conditions, which leaves some behavioral gaps for a mutation 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?

The description is a single, dense sentence that packs all essential information without fluff. The primary action ('Create a new ADR') is front-loaded, followed by precise details about the stub generation and the concurrency caveat. Every word earns its place, making it both succinct and structurally effective.

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 complexity (sequential numbering, placeholder sections, optional reindex) and the absence of an output schema and annotations, the description covers most critical behavior. It does not describe the response/return value or error handling, but the auto_reindex parameter in the schema partially addresses response contents. Overall, it is fairly complete for an agent to invoke the tool correctly, with minor 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 100%, so the schema already documents all parameters. The description adds no additional parameter-specific meaning beyond what is in the schema (e.g., that title is used 'verbatim in the heading' is already in the schema's description). It does provide broader tool behavior context, but not extra parameter semantics, matching the baseline of 3.

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

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

The description clearly states the tool's function with a specific verb and resource ('Create a new ADR') and goes into detail about what it does: allocate a sequential number, write a 'Proposed'-status stub with title and context, and fill remaining sections with placeholders. This distinguishes it from siblings like edit_adr, update_adr_status, and read_adr, making its purpose unambiguous.

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

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

The description implies usage is for creating a new ADR, but it does not explicitly state when to use this tool versus alternatives (e.g., when to edit vs. create, or when not to use it). It lacks explicit 'when not to use' guidance or mentions of sibling tools, so the agent must infer usage from the purpose alone.

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

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

With no annotations, the description carries the behavioral burden and does disclose the destructive action ('Replace'), the exact target (top-level section), and a rejection case ('Rejects the Status section'). It does not mention permissions or reversibility, but the core what-gets-changed behavior is clear.

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 tight sentence front-loads the action and target, then adds the single most important exception. Every word earns its place with no filler or repetition.

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

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

For a write tool with no annotations and no output schema, the description is nearly complete: it states what is replaced, at what heading level, and which use case is routed elsewhere. The auto-reindex behavior is already covered in the schema, leaving only minor omissions like behavior when the section does not exist.

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

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

Schema coverage is 100%, so all parameters are already documented in the input schema. The description's reference to '## heading' mirrors the section parameter's meaning but adds no new syntax or format details beyond what the schema states.

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

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

The description opens with a specific verb ('Replace'), a precise resource ('a single named top-level (##) section of one ADR'), and a clear scope. It also draws an explicit boundary against the 'Status' section, which distinguishes it from update_adr_status at a glance.

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

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

It explicitly names the alternative for status transitions—'use update_adr_status instead'—so an agent knows exactly when not to use this tool. The 'top-level (##)' qualifier also clarifies that this is not for editing nested or non-heading content.

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. 'Replace' clearly indicates a mutation, and the auto_reindex parameter (visible in the schema) hints at a side effect, but the description itself does not state that the operation modifies the file, whether it requires specific permissions, or what happens if the targeted section does not exist. It also omits any mention of error conditions or response format beyond what the schema implies.

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

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

A single, front-loaded sentence with zero filler. It immediately states the verb, target, and scope. Highly efficient.

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

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

For a mutation tool with no annotations and no output schema, the description is under-specified. It does not explain whether the section must already exist, whether new sections can be created, or how errors are reported. The auto_reindex parameter's behavior is only documented in the schema, not in the description, leaving an agent to infer the tool's side effects. The tool appears simple, but these gaps could lead to incorrect 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 100%, so the baseline is 3. The description does not add meaning beyond the schema; it merely restates the purpose. Parameters like content and section are already well-described in the schema, so the description does not compensate for any gaps—there are none.

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 provides a specific verb ('Replace'), a clear resource (a single named top-level (##) section of .context/project.md), and enough detail to distinguish it from siblings like edit_adr (targets ADR files) or write_project (likely a full rewrite). No ambiguity about what the tool does.

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

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

No explicit guidance on when to use this tool versus alternatives. It does not mention that it is specifically for editing existing sections of project.md, nor note exclusions (e.g., cannot create new sections, or should be preferred over write_project for partial edits). The implied use case is clear but not explicitly framed relative to 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?

The description discloses key behavioral details: the selection is deterministic and based on filename ordering, not semantic relevance. This is crucial for understanding how the tool behaves and prevents misinterpretation. No annotations are present, so the description carries this responsibility well.

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 that convey all essential information without any filler. The structure is efficient, front-loading the core purpose and then providing necessary usage guidance.

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

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

The description gives sufficient context for the tool's role: it identifies the file type, explains how the latest is determined, and tells the agent the next step (pass to load_context_files). It also warns against a common misuse (relying on snippets), making the tool's place in the overall workflow clear.

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 only parameter `project_path` is fully documented in the schema with acceptable formats (absolute path, owner/repo, or full URL). The description itself does not add extra semantic detail about the parameter, but with 100% schema coverage it does not need to. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: to deterministically find the most recent .context/sessions/*.md file. It specifies the resource type and the exact operation, leaving no ambiguity about what the tool does.

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

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

Provides explicit usage instructions: pass the returned path to `load_context_files` and warns against relying on the tool's snippets alone. This tells the agent exactly how to use the result and what to avoid, which is ideal guidance.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that the tool returns questions to ask the user, that answers feed into `bootstrap_context`, and that `project_path` triggers merging custom YAML questions. It does not cover error behavior or return structure, but the main behavioral traits 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?

Three sentences with no filler; the core purpose is front-loaded, and the workflow and optional behavior follow naturally. The repeated word 'pass' is slightly redundant but each 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?

The description gives a clear workflow and explains the optional `project_path` behavior, which is helpful given there is no output schema. However, it does not explicitly specify the shape of the returned question set or how invalid `target` values are handled, leaving some ambiguity for the agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: `target` is currently restricted to 'project' and maps to `.context/project.md`, and `project_path` controls whether repo-supplied `.project-bootstrap-questions.yaml` questions are merged in.

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 opens with a clear verb and resource: 'Get the interview question set for a bootstrap artifact'. It also differentiates the tool from the sibling `bootstrap_context` by explaining that answers are passed to that 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?

It describes the intended workflow: ask the user each question, then pass the answers to `bootstrap_context`. It also explains when `project_path` should be supplied to merge repo-supplied custom questions. It does not explicitly name alternatives or say when not to use the tool.

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 must fully disclose behavior. It only says 'Re-index...' without explaining whether the operation is destructive, whether it overwrites existing data, or what the impact is on the vector store. This is a significant gap for a mutation 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?

The description is a single two-sentence paragraph that is concise and front-loaded. The first sentence states the action, the second gives usage triggers. No unnecessary words, and each 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?

Given the tool's simplicity (one param, no output schema, no annotations), the description covers the basic purpose and usage triggers. However, it lacks details about the parameter and the effect on the vector store, making it minimally viable but not fully 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 only parameter is project_path, and the schema description coverage is 0%. The description does not mention project_path or provide any additional meaning beyond its name. It relies on the parameter name being self-explanatory, but adds no context about format or restrictions.

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: 'Re-index the .context/ directory into the vector store.' It also provides context on when to run it, which helps understand its purpose. However, it does not explicitly distinguish from siblings like search_project_context, but the unique action 're-index' sets it 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 gives clear triggers for use: 'after updating project.md, adding ADRs, or refreshing BUNDLE.md.' This provides good guidance on when to use the tool. It lacks explicit when-not-to-use instructions or alternatives, but the given context is sufficient for most cases.

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. It discloses the scope (all ADRs in .context/decisions/) and the lightweight nature (does not load full content), which is useful. However, it doesn't mention behavior like whether it follows symlinks, how it handles missing directories, or whether it sorts by number, though these are minor for a listing 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?

Two sentences with no wasted words. The core action and output format are front-loaded, and the usage guidance is concise. Every sentence earns its place.

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

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

For a simple listing tool with one parameter and no output schema, the description is nearly complete. It covers what the tool does, what it returns, and when to use it. The only minor gap is not describing error behavior (e.g., missing directory), but that's not essential for an agent 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 the single parameter. The description adds no additional meaning about project_path beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a specific verb ('List'), a precise resource ('every ADR in .context/decisions/'), and the output format ('lightweight table (number, title, status, filename)'). It clearly distinguishes itself from sibling tools like read_adr and read_adr_section by saying it lists metadata rather than loading full content.

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

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

The description explicitly says to use this tool before read_adr/read_adr_section to find which ADR is needed, without loading full ADR content. This gives clear when-to-use guidance and names the alternatives, making the selection decision unambiguous.

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

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

With no annotations, the description carries the full burden. It discloses that it lists top-level (##) section names in document order, which is useful. However, it does not state that it is read-only, what happens if the ADR is not found, or any error behavior. For a simple read operation, this is acceptable but not rich.

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

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

A single, front-loaded sentence that conveys the action, scope, and key detail (## headings, document order) with no wasted words. Highly concise and clear.

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 parameters and no output schema, the description covers the essential return value (section names) and scope. It could mention the return format (array vs. string) but that is a minor gap. Overall adequate for a straightforward read tool.

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

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

Schema coverage is 100%, so the parameters are already well-documented. The description does not add any parameter-specific information beyond what the schema provides, meeting the baseline of 3.

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

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

The description clearly states the verb ('List'), the resource ('one ADR's top-level (##) section names'), and the scope (single ADR). It distinguishes from siblings like read_adr_section (reads content) and search_adr_sections (searches) by specifying it lists only top-level headings in order.

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 when to use it (when you need just the section names of a specific ADR) but does not explicitly mention alternatives or exclusions. No mention of read_adr_section for content or list_adrs for all ADRs. Guidance is inferred rather than stated.

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

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

No annotations provided. Description only adds 'accessible via configured provider', but does not disclose pagination, rate limits, auth needs, or behavior when provider is unavailable.

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, compact and front-loaded. No unnecessary words; every sentence adds value.

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

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

No output schema, and description omits return format, pagination, ordering, or error handling. For a simple list tool, it is borderline adequate but lacks completeness.

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

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

Schema coverage is 100% and parameter description in schema is clear. Description repeats essentially the same info, adding no new semantics 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?

Description clearly states the action (list) and resource (repositories), and distinguishes from sibling tools which focus on project context and sessions.

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

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

Explicitly advises using this tool for discovery in multi-tenant deployments before other tools, and mentions optional filtering. Lacks when-not-to-use or alternatives, but siblings are unrelated.

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. It discloses that files are loaded into context and tagged with hashes for change detection, but does not explicitly state whether the operation is read-only or if there are any side effects beyond modifying the active 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?

The description is concise, consisting of two clear sentences, and front-loads the core action followed by useful detail. No extraneous information is included.

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 explains the tool's behavior and its relationship to reload_active_context_file, but does not mention what the tool returns or whether there is any output. Since there is no output schema, this gap is minor but 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?

Both parameters are fully described: 'files' explains the relative path format with an example, and 'project_path' lists the three accepted forms (absolute path, owner/repo, or URL). This exceeds the 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 clearly states the tool loads specific .context/-relative files into the active context, and explains the tagging mechanism with path and SHA-512 hash. This makes the purpose unambiguous.

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

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

The description provides explicit guidance to only pass files actually needed and to avoid loading the whole tree, but does not directly contrast with sibling tools like search_context_index or reload_active_context_file.

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 full burden. It discloses that the tool tags the content with path and SHA-512 hash for change detection, which is a behavioral trait beyond the schema. However, it does not explicitly state read-only semantics or side effects, leaving some ambiguity about permissions and mutability.

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

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

Two sentences, front-loaded with the core action and the hash tagging, and the alternative in the second sentence. No redundancy, every word 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 tool is simple, and the description conveys that it returns full raw content plus path and hash, which is sufficient for a read operation. It could mention error behavior, but given low complexity and no output schema, it is adequately complete.

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

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

Schema description coverage is 100%, and the description merely summarizes the parameter behavior ('by number or filename') without adding new meaning. It meets the baseline for high-coverage schemas but adds no extra value beyond what the schema already documents.

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

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

The description clearly states the tool reads one ADR's full raw content by number or filename, and explicitly names the alternative `read_adr_section` for partial reads, distinguishing it from that sibling. It is a specific verb+resource with no 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 provides explicit guidance to prefer `read_adr_section` when only one section is needed, which is clear when-not guidance. It does not enumerate all alternatives but gives a concrete selection rule that an agent can act on.

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 clearly signals a read-only operation. It also specifies the scope (single top-level section), which prevents misuse of the tool for nested sections. It could add edge-case behavior (e.g., missing section), but the core behavior is 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 behavior and examples come first, followed by the routing guidance. Every sentence adds value.

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

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

For a simple read tool with three fully documented parameters and no output schema, the description is complete. It specifies what is read, how to identify the section, and how to find section names if unknown. No critical operating detail is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the `section` parameter by specifying exact heading text and pointing to `list_adr_sections` for names, but it does not need to add more because the schema already documents all three parameters fully.

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: 'Read a single named top-level (##) section of one ADR', with examples of valid sections. This clearly distinguishes it from sibling tools like `read_adr` (whole ADR) and `search_adr_sections` (searching).

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

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

It explicitly tells the agent to use `list_adr_sections` first when the exact section name is unknown, giving a concrete decision rule. This is strong practical guidance for selecting the correct tool.

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 bears full burden. It discloses that it returns only title and status, not full content, and mentions behavior for legacy format. However, it doesn't disclose error cases, returns for missing ADRs, or whether it modifies anything. As a read-only operation, it's fairly clear, but more detail on responses would help.

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 waste. Purpose is front-loaded, and the legacy format note is a useful extra. Highly concise and effective.

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 parameters and clear schema. The description explains the lightweight nature and handles edge case of legacy format. Lacks explicit return format, but no output schema exists, and the description's clarity compensates. Complete enough for an agent to call 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 covers both parameters thoroughly (project_path and number_or_filename formats). Description doesn't add extra semantics beyond schema. With 100% coverage, baseline 3 is appropriate; no extra value added by 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 clearly states the tool reads an ADR's title and parsed Status without loading full content, distinguishing it from read_adr which loads full content. It also mentions handling legacy inline format, adding specificity. This differentiates it from sibling tools like read_adr and list_adrs.

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 use when you need only title and status, not full content, but does not explicitly say when to use read_adr instead. It could be clearer about avoiding this tool when full content is needed, but the context is reasonably 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 provided, the description carries full responsibility. It transparently discloses the comparison behavior and the three distinct outcomes: fresh content for changed files, 'no change' for unchanged, and 'not found' for deleted. This gives the agent a complete picture of the tool's behavior without hidden side effects.

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 concise, using two sentences to convey the core action and expected outcomes. There is no redundant or extraneous information, and the structure is logical, starting with the action and then describing the return behavior.

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

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

Although there is no output schema, the description explicitly explains what the tool returns for each possible scenario (changed, unchanged, deleted). With only two parameters and a clear return contract, the description is sufficiently complete for correct 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?

The schema already provides 100% coverage of both parameters, including descriptions for 'files' (list of path and known_sha512) and 'project_path'. The tool description does not add significant extra meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: checking whether files in active context have changed on disk by comparing SHA-512 hashes. It also distinguishes itself from the sibling tool load_context_files, which presumably loads files, by focusing on change detection and returning updated content only for modified 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 description implies usage when you need to detect changes to already-loaded files, and it clarifies that unchanged files yield a 'no change' message and deleted files yield 'not found'. It does not explicitly mention alternatives or when not to use it, but the purpose is clear enough for the agent to decide.

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 provided, so description carries full burden. It states the output location and naming convention but does not disclose overwrite behavior, directory creation, or any side effects. Basic but adequate for a simple write operation.

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

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

Two concise sentences front-load the key information: purpose, destination, and usage timing. 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?

Given simple parameters and no output schema or annotations, the description covers the essential aspects. It could mention whether the file is created/overwritten, but the overall completeness is high for the tool's complexity.

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 50%. The description adds meaning to 'summary' by listing what to include (work done, decisions, next steps). However, 'project_path' remains unexplained beyond its type, missing an opportunity to clarify its format or constraints.

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 tool saves a session summary to a specific file path, distinguishing it from sibling tools that index, load, or search project context.

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

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

Explicitly says to call at end of session with a concise summary, providing clear when-to-use guidance. Does not discuss alternatives or when not to use, but the context with sibling tools implies differentiation.

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

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

The description reveals that the tool returns snippets (not full content) and that a follow-up load_context_files is needed for full ADRs. It also implies a semantic search mechanism. However, it does not explicitly state read-only behavior or output structure, though these are not critical given the search 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?

The description is concise, consisting of two sentences that efficiently convey purpose, usage, and alternatives. It is front-loaded with the core action and includes necessary caveats without unnecessary detail.

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 simplicity and the existence of an output schema, the description adequately covers how to invoke it and what to do with results. The note to load full context files is particularly important and included, making the description sufficient for correct 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?

The schema provides descriptions for query and project_path, and the tool description reinforces their purpose. However, n_results is only given a default value without any explanation in either schema or description, leaving its meaning partially unclear to the agent.

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 tool's function: semantically searching architecture decision records within .context/decisions/. It also distinguishes this tool from alternatives like search_project_files and search_context_index, making its scope unambiguous.

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

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

The description explicitly instructs when to use this tool (find ADRs for the current task) and when to use an alternative (search all project files via search_project_files). It also advises not to rely solely on snippets and to load full context files, providing complete usage guidance.

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

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

With no annotations, the description carries the burden. It conveys that this is a semantic, scoped search and implies read-only behavior, but it does not explain preconditions or what 'resolved' means, nor what happens when no matches are found.

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 action and scope are front-loaded, and the usage hint about prior discovery tools is immediately useful.

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

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

Combined with the input schema and output schema, the description gives an agent enough to call the tool successfully: scope, prerequisite identification step, and query semantics. Minor gaps around alternatives and result behavior are not critical.

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 75%, so the schema already documents most parameters. The description adds context that `number_or_filename` is the scoping mechanism and that the ADR should already be identified, but it adds no detail about `n_results` beyond the schema 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?

States a specific verb ('semantically search'), resource ('a single resolved ADR'), and scope ('by number or filename'). The phrase 'inside one ADR you've already identified' clearly differentiates it from searching the index across multiple ADRs.

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

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

Gives clear context: use it after identifying an ADR via `list_adrs` or `search_adr_index`. It does not explicitly state when not to use it or name alternative section-listing tools like `list_adr_sections`, but the intended usage is clear.

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

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

No annotations are provided, so the description must convey behavior. It discloses that the tool returns snippets and file paths ('find which files are relevant' and 'do not rely on this tool's snippets alone'), implying a read-only search operation. It does not explicitly state it has no side effects, but the nature of a search tool makes that clear. This is sufficient transparency, though not perfect.

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 concise, consisting of two sentences. It directly states the purpose, usage, and a caution without any unnecessary words or repetition. The structure is clean and easy to parse.

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 provides essential context for the tool's role in a workflow (search first, then load files) and warns against over-reliance on snippets. It does not detail the output schema, but the information about snippets and relevant files is enough for the agent to understand what to expect. Given the tool's simplicity, this is nearly 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 schema descriptions cover `query` and `project_path`, but `n_results` lacks a description (only a default of 5). The tool description does not elaborate on `n_results`, leaving its meaning to inference from the tool's purpose. Since schema coverage is 67% and the description adds no additional clarity, the parameter semantics are adequate but not enhanced.

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 tool's purpose (semantically search the whole indexed project context) and differentiates it from the sibling tool `load_context_files` by instructing to use this first and then pass file paths to the sibling. The verb 'search' and resource 'context index' are specific, making it 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 provides explicit usage guidance: 'Use this first to find which files are relevant to your task, then pass their paths to `load_context_files`' and 'do not rely on this tool's snippets alone.' This tells the agent exactly when to use this tool versus the alternative, leaving no ambiguity.

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 disclosure burden. It reveals that the search is semantic and returns snippets (implied by 'do not rely on this tool's snippets alone'), but it does not disclose details such as whether the query is case-sensitive, whether results are ranked, or any rate limits. It adds some behavioral context but lacks depth that annotations would typically cover.

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 sentences with zero fluff. It front-loads the core purpose, then immediately gives usage guidance and a caution. Every clause earns its place, making it efficient and easily parseable.

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 presence of an output schema (which covers return values) and a moderately simple tool with 3 parameters, the description covers the essential usage, workflow, and caveat. It tells the agent how to integrate results with another tool, which fully addresses the typical decision points for calling this 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 67% (query and project_path are described). The description adds minimal insight beyond the schema; it implies query is natural language but says nothing about n_results semantics or how project_path determines the search scope. It does not compensate for the undocumented n_results parameter, so a baseline 3 is appropriate.

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

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

The description states a specific verb ('semantically search') and a precise resource ('past session summaries under .context/sessions/'). It clearly distinguishes this tool from siblings like search_context_index and search_adr_index by scoping to session summaries, leaving no ambiguity about what it searches.

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 explicitly says when to use it ('to find prior session notes relevant to a topic') and provides a clear follow-up action ('pass their paths to load_context_files'), while also cautioning not to rely on snippets alone. This gives the agent an explicit workflow and redirects to a sibling tool appropriately.

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 disclosure burden and does it well: it exposes validation behavior (rejects unknown statuses), preconditions (target ADR must exist for superseding), and a destructive side effect (removes the 'ADR Review Discussion' section once 'Accepted' is reached). It stops short of describing failure/error behavior or permissions, which keeps it below a 5.

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

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

The core action is front-loaded ('Transition one ADR's Status') and every guardrail clause carries distinct information with no redundancy. It is dense — a single long sentence — but the semicolon-separated enumeration keeps the overload reasonable for a tool with this many behavioral rules.

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?

Everything needed to invoke the tool correctly is present: valid statuses, precondition checks, the destructive side effect, and the cross-parameter dependency on 'explanation'. With no output schema, the missing piece is return-value semantics — the description never says what a successful transition returns — though the auto_reindex schema hint partially addresses the response shape.

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

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

Schema description coverage is 100%, with all five parameters fully documented in the schema, establishing the baseline of 3. The description's mention of the 'explanation' requirement largely restates the schema's own description of that parameter, adding no new semantic content beyond cross-referencing it.

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

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

States the action precisely — 'Transition one ADR's Status' — with singular scope and a lifecycle-management framing that the guardrails reinforce. It is clearly distinguishable from read_adr_status (read-only) and from edit_adr/create_adr, which are general-purpose rather than status-transition-specific.

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 context is implied rather than stated: the guardrails tell an agent what must be true before calling a transition (target ADR exists for 'Superseded by ADR-XXXXX', Decision section or explanation for 'Accepted'). However, no alternative tool is named explicitly and no when-not-to-use condition is given, leaving an agent to infer that edit_adr is the route for non-status changes.

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 of behavioral disclosure. It only states the action 'overwrite' and does not mention that this destroys existing content, the auto_reindex behavior (default false and manual reindex reminder), or any side effects. This is insufficient for an agent to understand the consequences of invocation.

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 is efficient and front-loaded with the core purpose. While it is very brief, the conciseness dimension rewards minimalism without sacrificing clarity, so a 4 is appropriate.

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 incomplete for a tool with three parameters and no output schema. It omits key details such as the auto_reindex parameter's default behavior and its reminder, the accepted formats for project_path (owner/repo, URL), and when to use this tool instead of edit_project. An agent lacks necessary context to invoke it correctly and safely.

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 full descriptions for all three parameters (content, auto_reindex, project_path) with 100% coverage. The description adds no additional meaning beyond what the schema already states, so it meets the baseline of 3. It neither enhances nor detracts from 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 'Overwrite the full content of .context/project.md.' clearly states a specific verb (overwrite) and resource (project.md). It is unambiguous about what the tool does, though it does not explicitly differentiate from sibling tools like edit_project, which could be for partial edits. The scope is implied but not stated.

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 alternatives. The description does not mention edit_project or any conditions for choosing write_project over it. There is no context about prerequisites, such as whether the project must already exist or the file must be present.

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