project_bootstrap

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

Annotations already declare read-only, non-destructive, idempotent behavior. The description adds valuable context beyond these: it does not return full rule/skill bodies, lease_id is optional, and repo content is untrusted. This security warning and the limitation on return content are significant behavioral disclosures not present in annotations.

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

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

Three sentences front-load the purpose, followed by a limitation, a side-effect note, and a security warning. Every sentence carries essential information with no redundancy or excessive 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?

The description covers the tool's purpose, limitations, safety profile, and security stance, which is strong. However, parameter semantics for 'paths' and 'project' remain ambiguous, which is a critical gap for correct invocation. The presence of an output schema mitigates the need to describe return values, but the parameter ambiguity prevents a higher score.

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%, yet the description only clarifies that lease_id is optional. It does not explain the meaning or usage of 'paths' or 'project', leaving the agent to infer them from the tool name and defaults. With three parameters and no schema descriptions, the description must compensate more but only touches one parameter.

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

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

The description opens with 'First orientation for a registered project' and enumerates specific contents (instruction manifests, skill manifests, VCS summary, warnings, recommended_reads). It explicitly distinguishes itself from related sibling tools by stating 'Does not return full rule/skill bodies', making it clear this is a summary orientation rather than a detailed retrieval tool.

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

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

The phrase 'First orientation' implies use when initially working with a project, and the statement that it does not return full rule/skill bodies hints that other tools (like project_instructions or project_skill_read) are for those details. However, it does not explicitly name alternatives or provide when-not-to-use conditions, so it falls just short of full guidance.

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