aap_create_project

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

Annotations already indicate a non-read-only write operation (readOnlyHint=false) and non-destructive behavior (destructiveHint=false). The description adds the return format (JSON with project id, name, initial status) and the Git/SCM origin, but does not disclose side effects like whether a project sync is triggered or permission requirements.

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: a one-sentence purpose, a helpful example, and clearly labeled Args/Returns sections. Every line earns its place, and the structure is immediately scannable.

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

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

The description covers the core purpose, provides an example, and states the return shape. With an output schema present, return-value details are not the description's burden. Combined with the schema's rich parameter descriptions, this is mostly complete, though it lacks guidance on manual (non-SCM) projects and post-creation behavior like syncing.

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 description only says 'params (CreateProjectInput): Project configuration' with 0% coverage of the 9 nested properties. The input schema has detailed per-property descriptions, but the description itself does not compensate. The example hints at name and scm_type only, leaving other fields (scm_clean, credential_id, organization_id, etc.) unexplained in the 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 opens with a clear verb+resource+source: 'Create a new AAP project from a Git/SCM repository.' The example ('Create a new project called redis-automation from GitHub') reinforces the purpose and distinguishes this from sibling create_* tools like aap_create_organization or aap_create_inventory.

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 a concrete example, implying the tool is used for creating source-controlled projects, but it does not explicitly state when to use this tool versus alternatives (e.g., manual projects via scm_type=''). No exclusions or conditions are mentioned.

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