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

Adds meaningful behavioral assurances beyond the readOnly/idempotent/non-destructive annotations: 'Makes no network calls and never returns the token itself.' This is important safety context for an auth-status tool and goes well beyond what annotations already state.

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 dense but each clause earns its place: the first sentence lists the diagnostic fields, the second adds safety behavior, and the third gives a usage directive. It is front-loaded with the core purpose and contains no fluff.

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 zero-parameter read-only status tool with no output schema, the description is complete: it lists every relevant status dimension and the specific trigger for calling it. An agent has enough to decide when and why to invoke it.

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 tool takes zero parameters, so the baseline is 4. The description compensates by enumerating exactly what information the status output will contain, which is more useful than a bare schema with no properties.

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?

States a specific diagnostic purpose: reporting Google connection status, token presence/source, expiry, account email, OAuth scopes, and credential locations. This clearly distinguishes it from sibling auth-flow tools like start_login, finish_login, and logout.

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 an explicit trigger: 'Call it first when other tools report the server is not connected.' It does not explicitly list when not to use it or name an alternative, but the diagnostic role relative to the login/logout siblings is clear.

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

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

Beyond the annotations, the description discloses permanence, irreversibility, thread deletion behavior, the fact that force only works with app authentication, and the empty-object success response. It also explains that PERMISSION_DENIED is a permission rule rather than a missing scope, which is valuable diagnostic 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 information-dense but well organized: core action first, then permissions, then failure modes, then warnings, then return value. Every sentence earns its place, and critical caveats like irreversibility and force-auth restriction are explicitly surfaced.

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 destructive tool with no output schema, the description is remarkably complete. It covers authorization contexts, error conditions, the force edge case, irreversibility, a pre-deletion safety step, and the success return value. An agent has everything needed to decide whether and how to invoke it correctly.

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 100%, so the baseline is 3. The main description largely restates the parameter semantics already present in the schema, such as the message name source and the force authentication constraint, without adding meaningfully new parameter-level detail.

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 a specific verb and resource—'Permanently deletes a message'—and immediately clarifies scope by distinguishing own messages from space-manager deletions. This makes the tool clearly distinguishable from siblings like get_message, send_message, and update_message.

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 explicit operating conditions: user vs. manager permissions, PERMISSION_DENIED vs. FAILED_PRECONDITION, and when force=true is valid. It also instructs the agent to read with get_message before deleting if content matters. It does not explicitly mention update_message as the non-destructive alternative, which keeps it just short of a perfect score.

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

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

The annotations already signal read-only, idempotent, and non-destructive behavior, and the description adds valuable context beyond those: it returns HTTP 404 when no DM exists, it cannot create DMs, and it accepts multiple user identifier formats. This gives an agent accurate expectations about failure modes and limitations.

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?

Three sentences with no filler. The core behavior is front-loaded first, followed by the critical 404 limitation, and then the accepted input formats. Every sentence adds necessary information for correct invocation.

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 simple single-parameter tool, the description covers the return value, the error case, the creation limitation, and the accepted user identifier syntax. No output schema exists, so the inline explanation of the returned space name is sufficient for an agent to chain the result into send_message.

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 coverage is 100%, so the schema already fully documents the single 'user' parameter. The description repeats the accepted identity formats and adds that the user is the counterpart of the authenticated user, which is useful but not essential 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?

States a specific verb and resource: it finds the EXISTING direct-message space between the authenticated user and another user, and clarifies it returns the space name for use with send_message. This clearly distinguishes it from siblings like get_space or search_spaces because it targets DM lookup by user.

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?

Explicitly explains both when to use the tool (finding an existing DM space to send a message into) and when not to use it (when no DM exists, since it cannot create one). It names the alternative path — spaces.setup via raw_request — making the decision boundary clear.

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

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

The description richly discloses behavior beyond the annotations: it saves tokens to an owner-only file, verifies via a read-only identity call, handles partial permission grants by still saving the login and reporting missingScopes, replaces previous logins with best-effort refresh token revocation, and returns previousAccountEmail. This goes well beyond the basic annotation hints.

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 dense but efficient: four sentences cover purpose, postcondition, partial-permission handling, and account-replacement behavior. Every sentence adds meaningful information, and the key purpose is front-loaded in the first sentence.

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 zero-parameter tool with no output schema, the description is complete: it explains what happens, what is returned, what happens on partial permission, and what happens when switching accounts. No important invocation or result information is missing.

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 tool has zero parameters, so the input schema already covers everything. The description adds value by explaining what the response contains and the side effects of invoking the tool, which is useful context even though no parameter documentation is needed.

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 finishes the second step of Google login, saves tokens to an owner-only file, verifies the login via a read-only identity call, and returns account email and granted scopes. This distinguishes it from the sibling start_login by explicitly labeling it as the second step and describing its specific outcome.

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 clear context: this is the second step after browser consent, and after success every tool works immediately without restart. It also clarifies behavior under partial permission grants and account replacement, but it does not explicitly name alternatives or state when not to use it, so it falls short of full when/when-not guidance.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive. The description goes far beyond that by disclosing the auth split (user credentials return an error), the short-lived nature of downloadUri/thumbnailUri and their browser-only suitability, and the fact that the metadata is duplicated in get_message. This is rich behavioral context with no contradiction to the annotations.

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 longer than average, but every sentence earns its place: return fields, auth restriction, alternative location for the same data, and endpoint boundaries for download/upload. The core action is front-loaded, and the supporting details are logically ordered with explicit notes.

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 single-parameter read-only metadata fetch with no output schema, the description covers everything an agent needs: input source, returned fields, authentication constraints, the sibling alternative, and related endpoint routing. Nothing is missing for correct invocation and interpretation.

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 100%: the only parameter, 'attachment', is already described as 'The attachment resource name from a message's attachment[].name.' The tool description repeats this origin but adds no new meaning beyond the schema. Baseline 3 is appropriate because the schema carries the semantic load.

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 a specific verb and resource: 'Fetches metadata of one message attachment by its resource name.' It lists the exact fields returned and explicitly distinguishes this from get_message, which already embeds the same metadata. An agent can immediately tell what this tool does and how it differs from its closest sibling.

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 an explicit when-to-use and when-not-to-use: it accepts only APP (service-account) authentication, while user-auth flows should read the same metadata from get_message's attachment[] field. It also routes raw byte downloads to the media endpoint and uploads to the upload endpoint, both outside this server's tools. No inference is required.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses detailed behavioral traits: it enumerates the returned message fields, explains custom-id name resolution, and explicitly states that deleted messages return deletionMetadata instead of content. This gives an agent accurate expectations about response shape and edge cases without an output schema.

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 front-loaded with the core operation and then adds compact, high-value details. Every sentence earns its place: the field list summarizes the return shape, the custom-id note clarifies an important input variant, and the deletion behavior warns about a key edge case. There is no fluff.

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?

Given the simple single-parameter schema, rich annotations, and absence of an output schema, the description is complete. It covers what the tool returns, the accepted input forms, and the deletion edge case. Nothing essential is missing for an agent to invoke this tool correctly.

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 schema already documents the message parameter with a pattern and example, providing 100% coverage. The description goes further by explaining that custom-id names are also resolved, which is a meaningful semantic addition that tells the agent this parameter accepts more than just canonical names returned by list_messages/send_message.

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 a specific verb and resource: 'Fetches one message by its full resource name,' which clearly distinguishes it from list_messages and other siblings. It also lists the message fields returned and special behaviors like custom-id resolution and deletion metadata, making the tool's scope unambiguous.

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 implies the correct usage context: use this tool when you have a full message resource name, typically from list_messages or send_message, and it notes that custom-id names are accepted for messages sent with message_id. It does not explicitly contrast with alternatives like get_attachment or list_messages, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. Description adds behavioral context beyond that by explaining the meaning of spaceThreadingState (THREADED_MESSAGES means threads; otherwise flat) and highlighting that the returned data can validate a space id before a write. No contradiction.

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: the first packs the return contract, the second gives two precise use cases. No wasted words; the most important information is front-loaded.

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 one-parameter, read-only, idempotent tool, the description covers what is returned, the threading semantics, and when to call it. With no output schema, the explicit field list plus use cases is sufficient for an agent to invoke and interpret the result correctly.

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 100% and the single parameter 'space' is fully documented in the schema (id formats and sources). The description adds context that the parameter is used to confirm an id, but doesn't provide new parameter-level detail beyond the schema, so baseline 3.

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?

Description opens with a specific verb and resource — 'Returns one space's details' — and enumerates the exact fields returned (displayName, spaceType, spaceDetails, spaceThreadingState, membershipCount, createTime, settings). This clearly distinguishes it from sibling list_spaces and search_spaces by scope (one space).

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 explicit use cases: check the threading model before send_message with a thread, or confirm a space id before writing. It doesn't name alternatives or state when not to use it, but the stated conditions are concrete enough for an agent to select it.

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

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

Annotations already carry readOnlyHint, idempotentHint, and destructiveHint, so the description needn't repeat those. It adds beyond annotations: required OAuth scope (chat.memberships.readonly or chat.memberships), the space-membership prerequisite, and behavioral nuance such as INVITED/NOT_A_MEMBER states and inclusion of Google Groups.

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?

Three purpose-dense sentences: output shape, filter semantics, and required scope. Every sentence earns its place and there is no filler, though the first sentence is packed and could be slightly more 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?

With no output schema, the description takes on the burden of explaining return values, and it does so thoroughly (name, member, role, state with enumerated values). It also covers prerequisites and the main filters. It omits pagination details and error conditions, but page_size/page_token are covered in the schema.

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 already documents all 6 parameters, so the baseline is 3. The description adds value by explaining that role filters to managers/members, show_invited surfaces invited-but-not-joined users, show_groups includes Google Groups, and that the 'name' field is the handle for manage_members. page_size and page_token are already well-described 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?

States a specific verb ('Lists') and resource ('memberships in a space'), then enumerates exactly which fields are returned (name, member, role, state). This distinguishes it from siblings like list_spaces and get_space, and it even notes how the returned name maps to the manage_members tool.

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?

Describes clear context: use this to see memberships, roles, states, and to obtain the membership handle manage_members needs. It also states prerequisites (scope and space membership). It does not explicitly name an alternative or say when-not-to-use, so it stops short of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses meaningful behavior: messages from blocked members/spaces are included, show_deleted includes tombstones, and the tool works only with user authentication. This adds context about what the tool returns and its access constraints, well beyond what annotations alone convey.

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 information-dense, with no filler. Core purpose is front-loaded, followed by filters, ordering, deletion behavior, polling guidance, and authentication requirements, with each sentence contributing distinct and useful information.

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?

With 7 parameters and no output schema, the description compensates well by listing the returned fields, filter semantics, pagination strategy, deletion behavior, and auth constraints. An agent has enough context to decide when to call this tool and to construct a correct request.

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 100%, so the schema already documents each parameter. The description adds value by explaining output fields, the default ordering, the meaning of created_after for incremental polling, and that text filtering must happen client-side, though a minor ambiguity remains around calling only created_after and thread_name 'filters' when show_deleted also filters.

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 a specific verb and resource: 'Lists messages in a space', and further clarifies scope by including messages from blocked members and spaces and enumerating returned fields. This clearly distinguishes the tool from siblings like get_message (single message), list_spaces, and send_message.

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 provides clear operational guidance: there is no text search, clients must match client-side, and users should poll incrementally with created_after + page_token. It also states authentication requirements and scope prerequisites, though it does not explicitly name alternative tools for text search or single-message retrieval.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: results are limited to spaces the authenticated user belongs to, results are unordered, pagination uses nextPageToken, and space_type filters server-side. This is strong complementary behavioral detail.

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?

Three dense but efficient sentences. The core purpose and returned fields are front-loaded, followed by usage guidance and pagination details. Every sentence earns its place with no filler or repetition of schema content.

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 read-only list tool with rich annotations and a fully documented schema, the description covers required output fields, pagination, ordering, server-side filtering, and the tool's role in the broader workflow. Nothing essential for an agent to select and invoke it correctly is missing.

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?

Input schema covers all three parameters at 100%, so the baseline is 3. The description adds meaningful extra semantics by explaining that space_type narrows results server-side and that page_token comes from nextPageToken, which helps an agent use the parameters correctly beyond the schema text.

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?

States a specific verb ('Lists'), resource ('spaces the authenticated user is a member of'), and the key returned fields. Clearly differentiates itself from search_spaces by noting this is the discovery entry point and that no text search is available here.

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?

Explicitly positions the tool as the discovery entry point whose results feed other tools. Provides concrete routing guidance: use space_type for server-side narrowing, match displayName client-side, and use search_spaces for admin-only text search. Also explains pagination behavior.

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

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

The description goes well beyond the annotations by naming the revocation endpoint, specifying that the local credentials file is deleted, clarifying that env-var tokens are unaffected, and mentioning the envTokenStillSet response field. This is exactly the kind of behavioral detail an agent needs for a destructive action.

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 compact sentences with the most critical action front-loaded. Every sentence adds important information, and there is no fluff or repetition of schema fields.

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 covers the action, side effects, exception case for env-var tokens, and a relevant response field. For a zero-parameter tool with no output schema, this is fully sufficient for an agent to use it correctly and predict its impact.

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 tool has zero parameters, so there is no parameter meaning to add. The description correctly focuses on the action and side effects rather than inventing parameter details. Baseline 4 is appropriate because the schema is trivially complete.

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 states a precise verb and resource: it revokes the stored Google token and deletes the local credentials file. The title 'Disconnect from Google' aligns with the behavior, and the description clearly distinguishes this from other auth-related sibling 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 gives clear context: use this to revoke and delete stored credentials. It also explicitly tells the user that env-var tokens are not touched and must be removed manually, which is a valuable usage caveat. It does not name alternatives, but no true alternative exists for this action.

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

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

The description goes well beyond the annotations by disclosing that add/update_role/remove require MANAGER role, that PERMISSION_DENIED is a Chat role rule rather than a network issue, and that remove immediately kicks the user and is not undoable. It also explains that re-adding creates a fresh invitation. This meaningfully supplements the destructiveHint and openWorldHint annotations.

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 dense but well organized by action, with the critical permission warning front-loaded. Every sentence conveys necessary operational detail, and no filler or redundant phrasing is present.

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 multi-action tool with no output schema, the description fully covers each action's behavior, parameter requirements, permission prerequisites, failure semantics, and edge cases. An agent has enough context to invoke the correct action and interpret common failures.

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 schema already provides 100% description coverage for all parameters, so the baseline is 3. The description adds value by mapping each action to its required parameters (e.g., add uses space+user, update_role uses member_name+role) and clarifying optional/default behavior for role. This exceeds the schema's documentation without fully replacing it.

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 that the tool manages space membership and enumerates each action (get, add, update_role, remove) with specific behavior. It distinguishes itself from sibling tools like list_members (for checking roles) and raw_request (for Google Groups/Chat-app memberships).

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 explains when each action is appropriate, when it is not (e.g., cannot add members in DMs/group chats), and which sibling tools to use instead (list_members for role checks, raw_request for special membership types). It also states the required scope and manager permission, making tool selection unambiguous.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses specific error outcomes (ALREADY_EXISTS, PERMISSION_DENIED), the requirement to use the authenticated user's own reactions for removal, scope prerequisites, and the raw_request path for custom emoji.

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 dense but every sentence carries operational or behavioral information. It is front-loaded with the core purpose and then efficiently covers actions, errors, custom emoji, and scopes without repetition.

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 three-action tool with no output schema, the description is remarkably complete: it explains return contents for list, error conditions, permission boundaries, page_size/page_token usage, and scope requirements. Nothing critical is left for the agent to guess.

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?

Although schema coverage is 100%, the description adds important semantic detail: emoji must be the literal unicode character rather than a shortcode, reaction_name comes from list output, page_token enables pagination, and action determines which parameters apply. This meaningfully exceeds the bare 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 states a specific resource ('Emoji reactions on a message') and enumerates three distinct actions (add/list/remove), so an agent immediately understands what the tool does. It stands apart from sibling message and space tools because it is the only one operating on reactions.

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 clear per-action usage context, including filtering for list, deleting only via reaction_name, and the authenticated-user restriction. It also explicitly routes custom workspace emoji to raw_request, which is a useful alternative; however, it does not provide broad when-to-use vs. sibling-tool guidance.

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

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

Annotations already communicate destructive/read-only/idempotency hints, and the description adds useful behavior facts: the Bearer token is added automatically, the method defaults to GET, paths may include query strings, and media endpoints are not proxied. It does not elaborate on destructive consequences, but destructiveHint already covers the safety profile.

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 dense but every sentence earns its place: purpose, examples, defaults, and exclusions are each covered in one compact span. The long example list is justified for an open-ended raw tool, and the media exclusion is clearly separated.

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 raw escape-hatch tool, the description is largely complete: it covers path semantics, method default, body usage, auth behavior, query strings, and media exclusion. The only minor gap is an explicit statement about the response shape, but raw responses are inherently variable and no output schema exists.

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 schema covers all parameters, so the baseline is 3, but the description adds real value with concrete path/method/body examples (POST v1/spaces, PATCH v1/spaces/<id>, v1/spaces:setup) and clarifies that paths are relative with optional query strings. This goes beyond the schema's field descriptions.

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 states a specific verb and resource: 'call any Google Chat API v1 path directly' and clearly positions the tool as an 'Escape hatch' for requests typed tools don't cover. Concrete examples like creating spaces, setting up DMs, and custom-emoji reactions make it easy to distinguish from the typed siblings.

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?

It explicitly says when to use the tool: 'for requests the typed tools don't cover' and provides a clear exclusion: 'Not for media: attachment upload/download use different endpoints... that this server does not proxy.' This gives an agent enough information to choose raw_request over alternative typed tools.

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

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

The description adds meaningful behavioral context beyond the readOnlyHint, idempotentHint, and destructiveHint annotations: it runs with useAdminAccess=true, requires administrator authorization, returns PERMISSION_DENIED for non-admins, and enforces mandatory query filters. There is no contradiction with annotations.

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 dense but every sentence earns its place: purpose first, then access restrictions, then fallback, then query syntax with examples. Despite its length, it is efficiently front-loaded and contains no filler or repetition of schema details.

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 4-parameter search tool with no output schema, the description fully covers the key operational details: auth, scope, required query syntax, ordering, and alternative tool. Pagination parameters are already documented in the schema, so their absence from the description is acceptable.

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?

Although schema coverage is 100%, the description adds crucial semantics: it mandates that query must contain customer and spaceType, explains how to use displayName for name search, gives a concrete example, and enumerates valid order_by fields. This goes well beyond the schema's generic descriptions.

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 states a specific verb and resource: server-side search over all named spaces in the Workspace organization. It clearly differentiates this tool from list_spaces by emphasizing admin-only, organization-wide scope that includes spaces the caller does not belong to.

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 explicit when-to-use guidance: it is admin-only, requires specific OAuth scopes, and says anyone else gets PERMISSION_DENIED and should fall back to list_spaces with client-side displayName matching. This directly routes an agent to the correct alternative.

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

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

Beyond the annotations, the description discloses critical behavior: sends are never retried after 5xx/timeout, message_id reuse fails with ALREADY_EXISTS and can detect duplicate sends, and thread parameters are ignored in non-threaded spaces. This adds materially to the readOnly/idempotent/destructive hints.

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 dense but every clause earns its place, covering identity, scopes, formatting, threading, idempotency, return values, retry behavior, and exclusions. It front-loads the core action and distinguishes the tool from raw_request, making the length appropriate for the tool's complexity.

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 with no output schema and six parameters, the description is remarkably complete: it explains return fields, failure modes, duplicate detection, threading edge cases, and when to use an alternative tool. An agent has enough context to invoke it correctly and safely.

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?

Although schema description coverage is 100%, the description adds substantial meaning: markup syntax for text, thread_name sourced from thread.name, thread_key semantics, reply_option fallback vs or_fail, client- prefix rules for message_id, and space id formats. This goes well beyond the schema fields.

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 states a specific verb and resource: 'Sends a text message to a space AS THE AUTHENTICATED USER,' including identity and scope requirements. It also differentiates from sibling tools by explicitly carving out cardsV2 as app-auth-only and routing those to raw_request.

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 explicit when-to-use and when-not-to-use guidance: required scopes, membership prerequisite, thread fallback behavior, and the instruction to check with list_messages before re-sending after a 5xx/timeout. It even names raw_request as the alternative for app-auth card sends.

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

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

Annotations indicate idempotentHint=true (safe to call again) and readOnlyHint=false (it's a write). The description adds valuable context: it stores the client once in a shared path, is reused by all mcp-google-* servers, and tokens stay per-server. It also warns against pasting secrets. This goes beyond annotation basics, though it does not mention any potential side effects like overwriting an old client.

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 three sentences, each earning its place: the first explains what and source, the second details storage scope, the third directs to start_login. The critical warning is naturally integrated. It is not overly verbose and the essential info is front-loaded.

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 single-parameter tool with no output schema, the description covers key operational aspects: the source file, the storage path, the security precaution, and the follow-up step. The only minor gap is the absence of error conditions (e.g., if the file is invalid), but that is acceptable given the simplicity.

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 100%, so the baseline is 3. The description reinforces that the path is to the JSON file and adds the explicit 'must never be pasted into the chat' security guideline. It doesn't add much beyond the schema, but the security note is valuable enough to nudge to 4.

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 specifies a clear verb ('saves') and resource ('OAuth client credentials from the JSON file') and adds detail about the source and storage location. It does not explicitly distinguish from siblings, but the uniqueness of this tool among the listed siblings is implicit given its specific task.

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?

It provides clear guidance on when to use the tool: after downloading the JSON file and before starting login. It also mentions the prerequisite of calling start_login after. However, it does not explicitly state when not to use it or mention alternatives, though none are obvious.

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

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

Annotations already mark it read-only, idempotent, and non-destructive; the description adds valuable context beyond that: it works without credentials, warns that Testing-mode refresh tokens expire in 7 days, mandates publishing the consent screen, and guarantees it never asks users to paste secrets into the chat. No contradiction with annotations.

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?

Three dense sentences each carry unique, decision-relevant information: the checklist's contents, the shortened path when already configured, and the no-secrets guarantee. There is no filler or repetition.

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 zero-parameter instructional tool, the description fully covers purpose, usage timing, workflow relationships, and key behavioral safeguards. The lack of an output schema is acceptable since the tool's job is to present instructions, and the annotations already cover the operational profile.

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 is empty and parameter coverage is 100%, so there is nothing for the description to add about parameter semantics. The zero-parameter case earns the baseline 4.

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?

States a specific deliverable: a step-by-step checklist for connecting the server to Google, including project creation, OAuth client, consent screen, and handing the client JSON path to set_client. This clearly distinguishes it from sibling tools like auth_status or set_client.

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 explains when to use it (before credentials exist) and how the checklist shortens when an OAuth client is already configured, referencing set_client as the downstream consumer. It provides clear workflow context, though it does not explicitly say 'use this instead of X' for every alternative.

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

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

The description adds substantial behavioral context beyond the annotations: it does not open the browser itself, uses a one-shot listener on 127.0.0.1, exchanges the code locally, never passes it through chat, and has a 10-minute attempt lifetime. These details are not present in the annotations and provide meaningful operational guidance.

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 dense but every sentence earns its place: it covers user interaction, browser constraints, security, timeout, and next step without repetition or filler. The most important user-facing instruction is front-loaded.

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 with no parameters and no output schema, the description is fully complete. It explains the returned authorizeUrl, how to present it, what will happen afterward, and which sibling tool to call next.

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?

There are zero parameters, so the schema carries no burden and the description correctly avoids inventing parameter details. The baseline for a 0-parameter tool is 4; the description also reinforces that no configuration files or restart are needed.

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 'First step of connecting from the chat' and names a specific resource and action: start the Google login and return an authorizeUrl. It is clearly distinguished from siblings like finish_login and auth_status by positioning itself as the initial step.

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 states when to use it: as the first step of connecting, without editing config files or restarting the client. It also gives direct instructions to show the authorizeUrl to the user, ask them to open it in the browser, and call finish_login after the success page appears.

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

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

The description adds substantial behavioral context beyond the annotations: text is overwritten rather than appended, messages keep their name and thread, lastUpdateTime is set, clients show an Edited marker, and permission rules are explained. This complements the destructiveHint and readOnlyHint annotations without contradicting them.

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?

Three dense, front-loaded sentences cover behavior, permissions, side effects, and the raw_request alternative without redundancy. Every sentence earns its place, and the most important operational detail ('replaces text') comes first.

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 mutation tool with annotations already declaring readOnly=false and destructiveHint=true, the description provides the missing context an agent needs: auth restrictions, failure mode, side effects, and when to route to raw_request. No output schema exists, but the described side effects are sufficient for invoking the tool correctly.

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 100%: both text and message parameters are already documented with types, constraints, patterns, and examples. The description adds 'message name from list_messages/send_message' and the overwrite semantics, but these largely echo the schema, so the description adds no significant parameter-level value beyond the structured definitions.

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 a precise verb and resource: 'Replaces the text of an existing message'. It clearly scopes the operation to text-only updates via 'updateMask=text' and differentiates from siblings by stating the previous text is overwritten, not appended, which distinguishes it from send_message and delete_message.

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 concrete usage conditions: with user authentication only the authenticated user's own messages can be edited, and editing someone else's returns PERMISSION_DENIED. It also names an explicit alternative for a specific case: updating cards or accessory widgets requires app auth via raw_request.

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