Install ProAbono in this site, end to end (In-Site orchestrator)

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, and it does a thorough job. It discloses side effects: 'records progress in .proabono/installation.json' and 'writes no source file of yours.' It also reveals the execution model: detects stack, checks four prerequisites before generating, runs three steps in order, and resumes instead of starting over. It clarifies what the tool returns ('generates code and returns it'). This is rich, honest behavioral transparency for a complex orchestrator.

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 information-dense: every clause adds value (main action, prerequisite checks, steps, side effect, usage trigger, exclusion, return behavior). It front-loads the core purpose and then details the process. However, it is structured as a few very long run-on sentences, which could be broken into shorter, more scannable sentences. Minor deduction for readability, but no wasted words.

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 complex orchestration tool with no annotations and no output schema, the description is quite complete: it explains the full sequence, the prerequisites, side effects, and when to call. It does not state what happens if prerequisites fail, whether user confirmation is needed for the stack hypothesis, or the exact return format, but the schema already covers 'Ask the developer' for target_page and customer_area. The main omission is failure/abort behavior and how the agent should handle prerequisite failures. A more thorough tool would mention that, hence 4.

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 provides narrative context for parameters (e.g., 'detects the stack' for the `stack` parameter, 'authenticated customer area' for `customer_area`, 'how a ProAbono customer will exist' for `provisioning`), but it does not add concrete parameter-specific semantics beyond what the schema already states. It does not compensate by explaining formats, defaults, or relationships among parameters in a way the schema omits.

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 resource: 'Orchestrates the whole In-Site installation', then details the exact sequence (detect stack, check prerequisites, run three steps). It also distinguishes itself from siblings by being the end-to-end orchestrator that 'runs the three steps in order' (Customer Portal, Subscription Workflow, rights synchronization), corresponding to sibling tools like install_customer_portal and link_subscription_workflow. It additionally clarifies it never offers Widget/plug-in installs, making the scope unmistakable.

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 tells when to use it: 'Call it when a developer asks to install, set up or integrate ProAbono.' It also gives a clear exclusion: 'It installs ONE way, In-Site by code: it never offers a Widget or a plug-in.' This tells the agent when NOT to use it. The orchestration order and prerequisite checks further imply that if only a single step is needed, the appropriate child tool should be used, though not stated by name. Still, the trigger condition and exclusion are explicit enough for correct selection.

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