github_default_pr_base_branch

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

Annotations already establish read-only, idempotent, non-destructive, open-world behavior, so the bar for extra behavioral context is lower. The description adds meaningful context beyond that: it states the operation is governed and routes exclusively through the exact project/account connector authority, and it explains that 'effect' is required and must be read, and that Spring verifies it. It also notes approval_ref is used 'when resuming a write,' which clarifies the role of that parameter. This is useful material beyond annotation defaults.

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 compact and the parameter block is front-loaded after a one-line routing note, but it wastes its opening on a tautological label ('Github connector operation `default_pr_base_branch` (platform tool `github.default_pr_base_branch`)') that repeats the title. The param list is useful but reads like raw schema echo rather than curated help, and there is no framing sentence that tells the agent what 'default PR base branch' means or when this matters.

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 tool that presumably returns a branch name and lives in a large family of GitHub helpers, the description is thin. It never says what the operation does with a repo, what arguments the 'arguments' JSON expects, or what the output contains (even though an output schema exists, which reduces some of the burden). It also doesn't help an agent distinguish this from github_default_repo or github_get_branch. Given the zero schema description coverage and very generic sibling list, a richer description is needed.

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 carries the full burden for explaining parameters. The description lists all seven parameters with brief labels, and several of them are explained: effect is 'Required and must be read; Spring verifies it', approval_ref is 'Approved platform task UUID when resuming a write', and the routing param names are fairly self-explanatory. However, it does not explain the crucial 'arguments' JSON string content, which presumably holds the actual GitHub API parameters (owner, repo, etc.), and it leaves project_ref and connector_account_ref with only name-level glosses.

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 opens with an opaque name-only label and 'Github connector operation', which provides almost no semantic content about what the tool actually does. The only meaningful clue is the name itself ('default_pr_base_branch'), which suggests it retrieves a default pull-request base branch, but the description never states this explicitly, nor does it distinguish the tool from its many GitHub siblings such as github_get_branch or github_default_repo. It mentions the routing constraint, but that is operational context rather than purpose.

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?

The description gives one clear usage-related signal: it 'routes only through the exact project/account governed connector authority.' That tells the agent this tool is governance-scoped and should be used when authoritative connector routing is required, which is a useful contextual clue. However, it includes no explicit statement of when to use this tool vs alternatives, no examples, no mention of the actual branch-query scenario, and no guidance about which sibling tools are preferable for other GitHub branch-related needs.

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