github_update_repo

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

No annotations are provided, so the description carries the full burden. The description explicitly discloses the idempotent partial-update behavior ('Only provided fields will be updated. Leave empty to keep current value.'), which is critical for an update tool. However, it does not disclose potential side effects like archiving implications or whether explicit permissions are required for certain fields.

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 well-organized with an Args list that front-loads the key information. The 'Only provided fields will be updated. Leave empty to keep current value.' summary is highly efficient. The Args section is a bit verbose with repetitive 'empty = no change' phrasing, but this is justified for clarity given the field semantics.

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?

Has output schema (covers return value disclosure), and the description thoroughly documents all 8 parameters. For an 8-parameter partial-update tool with no annotations, this is reasonably complete. Minor gaps: doesn't mention whether archiving a non-empty repo is allowed or any auth requirements, but the core usage semantics are well covered.

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 0%, so the description must compensate for all 8 parameters. It provides semantic detail for each field, including the crucial 'empty = no change' semantics that differ from the schema's bare defaults. The private and archived fields are documented as expecting 'true'/'false' strings. This is valuable beyond 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 clearly states 'Update repository settings' with a specific verb and resource. It lists all supported fields (description, homepage, private, archived, default_branch). It distinguishes from create_repo and delete_repo, though it could more explicitly contrast with github_update_file (which updates file contents).

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?

Provides clear context that only provided fields are updated and empty means no change. This is important behavioral guidance for an update tool. However, it does not explicitly state when to choose this over alternatives like github_update_file or github_update_topics, though the resource scope (repository settings vs file/topic) makes this reasonably clear.

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