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

Annotations already declare destructiveHint=true, openWorldHint=true and idempotentHint=false. The description adds a genuinely useful mitigation ('Repositories are never deleted') and hints at which fields are tainted by the extra confirmation gate. But the mode distinction it relies on is opaque, and nothing is said about partial updates or what happens to unmentioned settings.

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?

Two sentences, but the first is a dangling fragment ('Without changes, read the settings.') and the second is a semicolon chain mixing field lists with an unexplained mode concept. It is short yet not front-loaded or scannable.

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?

A 14-parameter mutating tool with no output schema and a destructive annotation needs clearer coverage than this. The description leaves undefined the mechanism ('change anything') that governs the risky fields and says nothing about write conflicts, visibility semantics, or update behavior.

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 only 7% across 14 parameters, so the description must carry the semantic load. It does enumerate many field names (description, homepage, topics, has_issues, has_wiki, delete_branch_on_merge, merge methods, private, default_branch, archived), but omits has_projects, gives no types or defaults, and the field groupings hinge on undefined 'modes' that don't exist 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 does convey that gh_repo_settings reads repository settings when called without changes, and that the listed fields can be modified. However, it never states plainly 'update repository settings' and never distinguishes the tool from the nearby gh_repo sibling. An agent can infer purpose, but only by parsing a garbled sentence.

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?

'Without changes, read the settings' implies a read-vs-write pattern, but the referenced 'default mode' and 'change anything' are never defined and do not correspond to any schema parameter. No alternatives (e.g., gh_repo for reading, gh_create_repo for creation) are named, so routing guidance is effectively absent.

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