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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety bar is low; the description nonetheless adds real behavioral context beyond them — the exact scope of items returned, that organization-authored templates are never included, and that it never initiates execution. Crucially it explains how to interpret an empty result ("not a statement about any other aictrl capability"), which prevents a common misreading.

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?

Four sentences, each carrying distinct information: scope, prerequisite, exclusion boundary, and empty-result semantics. It is front-loaded with the core scope statement and contains no filler, though the exclusion and the empty-result caveat could be tightened into a single sentence without loss.

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 tool is simple (2 required, fully documented string params), has an output schema covering return values, and has rich read-only annotations. Given that, the description covers everything an agent needs: scope, prerequisite, state to verify first, and how to read an empty response.

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 both parameters are already documented with formats (owner/name pattern, ID provenance), making 3 the baseline. The description adds meaning beyond the schema by tying repository_full_name to a live-authorization/connected-repository precondition and pointing to get_started when that state is uncertain.

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 first sentence states a specific verb, resource, and scope ("List the first-party aictrl tasks that can run for one live-authorized repository"), and later sentences narrow it further by naming exactly which tasks (Code Review, PR Explanation) and excluding org-authored templates. An agent can distinguish this from start_task or from template-oriented siblings without opening the schema.

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?

It gives a concrete prerequisite-driven path: the repository must already be connected, and if unsure, call get_started with the same organization_id. It also implies the follow-up action by stating "Listing never starts work". It stops short of explicitly naming start_task as the tool to run a listed task, and never contrasts itself with list_workflows, so the routing guidance is clear but not exhaustive.

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