project_docs_bootstrap_plan

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description is consistent with that, adding useful specifics: the concrete artifacts the real bootstrap would touch (AGENTS.md, .issueops/*.md) and that content is derived from repository evidence. It omits the authorization model hinted at by the authority_file parameter and says nothing about idempotency or repeat-run behavior, which keeps it from a 5.

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

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

Two short sentences with zero filler, and the critical constraint (never writes files) is placed last for emphasis after the scoping sentence. Every clause carries information an agent needs.

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

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

There is no output schema, and the description does not say what a dry-run actually returns (a plan, a diff, a list of proposed file changes), which is the main thing an agent needs to interpret results. It also leaves the HTTP-vs-stdio authorization path unaddressed despite the authority_file parameter. Adequate for understanding intent, incomplete for using and interpreting the result.

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 most parameters are already documented; the description adds only the notion of 'repository evidence' as the input source. It does not clarify the relationship between the undocumented cwd parameter and the documented repo parameter, nor does it explain workspace_root versus repo. Baseline 3 is appropriate when the schema carries most of the semantics.

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

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

The description states a specific verb and scope: a dry-run bootstrap that would create or update AGENTS.md and .issueops/*.md from repository evidence. That is far more informative than the name, and the dry-run framing distinguishes it from the mutating siblings project_docs_append, project_docs_revise, and project_docs_read. It does not explicitly name those siblings, so differentiation is inferable but not spelled out.

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 word 'dry-run' implies you run this before applying changes, and 'never writes files' reinforces that it is a preview step, but the description never says when to pick this over project_docs_append/revise/route or what the prerequisite workflow is. The usage context is implied rather than stated, so an agent must infer the sequencing.

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