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

With annotations only declaring readOnly=false/destructive=false/openWorld=true, the description supplies the real behavioral burden: no token is ever accepted here, non-public repos fail with a prompt to connect via token, already-connected repositories are marked rather than duplicated (idempotency), and the operation is journaled. It also names the authorization roles (project lead, board admin, company admin).

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 core action is front-loaded in the first clause and every subsequent clause carries distinct information (token policy, idempotency, permissions, journaling). It is dense and heavy on em-dashes, but nothing reads as filler or repetition.

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 mutation tool with no output schema, it covers authorization, failure mode (private repo refusal), idempotency, side effects (journal entry), and the meaning of the optional flag. An agent has enough to call it correctly and predict the outcome.

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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond it: 'marking opens nothing by itself' clarifies openSource is a bookkeeping flag, and it ties openSource to the downstream set_project_public requirement. This is genuine value added over the schema's own wording.

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?

States a specific verb and resource with scope ('Connect one more GitHub or GitLab repository to a project, by its address') and clarifies that only one repository is added at a time. An agent can immediately tell this is an additive connect operation rather than the toggle (set_repository_open_source) or listing (list_repositories).

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?

Gives clear context: public repositories connect at once, private ones are refused and routed to a token screen, and openSource should be set only when the repo is the project's open source repository (which set_project_public depends on). It stops short of explicitly naming set_repository_open_source as the alternative for changing the flag later, so it is strong but not exhaustive.

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