GDP exposes a caller-effective tool surface rather than one permanent hard-coded list. Use discovery for the current catalog, target only repositories already open in GDP, read bounded context, diagnose before intake, and verify material outcomes from GDP evidence.
Discover the current tool surface
The exact GDP tool surface can vary by runtime version, caller profile, policy, enabled capabilities, and host behavior. AI hosts can also lazily load only the schemas needed for the current conversation. For that reason, a documentation page should not treat one historical tool count or one client-side schema snapshot as the permanent catalog.
When the relevant discovery tools are available, inspect the caller-effective GDP server or search the effective tool catalog before assuming a capability is missing. Use exact tool descriptors for argument, authority, and side-effect details when a material action depends on them.
Use list_repos to discover repository tabs currently exposed by GDP Desktop.
Use the current repo_id returned by GDP when a specific repository must be targeted.
Treat tab_index as visual order, not stable target identity.
Do not invent arbitrary filesystem paths or stale repo_id values as GDP targets.
A host showing fewer schemas than expected can be lazy loading or caller-effective filtering. Confirm current GDP catalog evidence before diagnosing a server capability regression.
Use bounded repository and context tools
GDP's repository-read family lets an AI inspect only the bounded context exposed through the selected open repository. Typical workflows combine repository identity and Git state with known-file reads, bounded folder or context packs, and repository text search when direct file selection is not enough.
Prefer the smallest context that answers the task. Read known relevant files together when possible, and use broader search or context expansion only when the location is genuinely uncertain. This improves privacy, performance, and reasoning quality at the same time.
Repository/state discovery can include list_repos, repository summaries, Git status, and diff reads.
Context reads can include known-file reads, bounded folder/context packs, and repository search.
Read tools do not become write permission merely because their output is sufficient to propose a change.
Selected file contents and other returned context may transit the configured AI host and gateway flow.
Separate patch intake from verification tools
Patch Doctor is the non-writing preflight and diagnosis layer for unified diffs. submit_patch performs preflight and places an acceptable candidate into repository-scoped local intake; it is not a direct apply RPC. Suggested Checks describe structured verification work for local policy evaluation rather than granting the hosted gateway shell authority.
After local policy applies a patch or runs a command, read fresh GDP evidence. Incoming-patch state, check-run summaries, bounded check output, repository status or diff, and operation/proof surfaces answer different questions and should not be collapsed into one generic success flag.
Read enough current repository context to prepare the change.
Dry-run or preflight the unified diff instead of assuming it still matches current source.
Submit only a coherent patch that passes the intake boundary.
Attach focused Suggested Checks when the change has a testable contract.
Read the resulting local evidence and continue from the first unproven step.
Tool availability answers what can be requested. The Authority & Evidence reference explains why a visible tool still does not prove permission or completion.
