generateConnectionModule

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

With no annotations, the description carries full responsibility for behavioral disclosure. It thoroughly describes the two-call flow, the existing-app detection logic (object + manual_patch vs full Application subclass), the return format (files[] with action values 'create' and 'manual_patch'), and platform-specific dependency differences (Android vs iOS). It also discloses that re-running with updated capabilities regenerates the bootstrap and mentions the 'no clobber' promise.

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 long but well-organized with bold section headers and clear separation of concerns. It front-loads the core purpose, then covers usage, platform nuances, and edge cases. While every section earns its place, there is some redundancy (e.g., the emphasis on capabilities-derived path appears twice) and the platform nuance section is quite dense, so a slight tightening could improve conciseness without losing 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?

Given the tool's complexity (8 parameters, multiple platforms, two-call flow, existing-app detection) and the absence of an output schema, the description leaves little uncovered. It explains the return value, references searchDocs('file_actions') for handling actions, covers platform-specific behaviors, and handles edge cases like greenfield vs existing app. It is exceptionally complete for a tool of this scope.

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 adds substantial meaning beyond the input schema. It explains how `capabilities` drives the scaffold type (VOICE vs DEVICE) and the derived path, how `placement` is used across calls, and how `projectPath` triggers existing-app detection. It also clarifies that `appPackage` is decoupled from store bundle ids, which is not apparent in 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?

The description opens with 'One-shot project scaffold — emits the bootstrap module that wires `Extentos.create(...)` into the host app', which clearly states the verb, resource, and output. It goes on to detail what is emitted (build-script changes, dependencies, permissions, integration manifest), and distinguishes itself from siblings by explicitly positioning it as the first generation tool and contrasting with inspectIntegration for already-installed projects.

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 states when to use ('USE as the first generation tool when scaffolding a fresh project') and when not to ('DON'T USE when Extentos is already installed'), even naming the alternative tool (inspectIntegration). It also provides detailed instructions on the two-call flow (without and with placement) and gives concrete guidance on how to handle existing apps via projectPath.

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