Start Google Auth

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

Beyond the minimal annotations, the description discloses that this is a legacy OAuth 2.0 tool, disabled when OAuth 2.1 is enabled, and that authentication is normally handled automatically by the system. It also explains the manual tool's role in re-authentication, proactive auth, and retry scenarios, which is rich behavioral context.

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-structured: a clear opening statement, a critical legacy note, a numbered list of use cases, and a closing recommendation. Every sentence carries distinct information without redundancy or filler.

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?

The description thoroughly covers purpose, usage conditions, alternatives, and legacy/automatic behavior, and the output schema can handle return-value documentation. However, it is not fully self-contained because it leaves parameter semantics unexplained, which is a meaningful gap for an agent deciding what to pass as service_name.

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?

The input schema has 0% parameter description coverage, and the description does not compensate by explaining either parameter. It never names service_name or user_google_email, nor does it clarify expected formats, allowed values, or how to choose the service. The phrase 'different credentials' only weakly hints at user_google_email, leaving the agent to guess at parameter meaning.

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 the tool's purpose: 'Manually initiate Google OAuth authentication flow.' It identifies the specific action and resource, and distinguishes itself from the long sibling list by being the explicit authentication entry point for Google Workspace tools.

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 explicitly lists when to use the tool with three concrete conditions and directly advises that in most cases the agent should simply call the needed Google Workspace tool instead. It also covers the failure/retry scenario, making the when-to-use and when-not-to-use guidance unambiguous.

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