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

Goes well beyond the annotations by disclosing error codes (private_repository_needs_credential, installation_lacks_repository), the required scope (mcp:admin), the side effect (first attach dispatches an indexing job), and the response fields (visibility, credential, indexing_status, indexing_job_id). This tells the agent what gets created and how to poll without contradicting the declared idempotent/non-destructive profile.

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?

Dense but well-organized, front-loading the core attach action and the public/private fork. Most of the remaining text earns its place by surfacing error codes and return fields, though the sentence is long and could be split for faster scanning.

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?

With no output schema, the description compensates by describing the return payload (visibility, credential, indexing_status, indexing_job_id) and the auth requirement. Nothing an agent needs to invoke and follow up correctly is missing.

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 genuine meaning: it explains that installation_id must come from list_installations and that it is refused when the installation lacks access, interpreting the parameter for the agent rather than restating it.

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+resource ('Attach a GitHub repository to a project') and immediately clarifies scope ('owner + repo_name; clone URL derived; projectId defaults to the bound / default project'). This distinguishes it clearly from siblings like list_repositories and reindex_repository without opening either 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?

Gives explicit routing context: public repos need nothing else, private repos need installation_id from list_installations or a workspace PAT, else the attach is refused. It names the sibling that supplies the credential. It stops short of explicitly contrasting with reindex_repository (re-attach already-indexed repos), so it is strong but not fully exhaustive.

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