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

Annotations provide readOnlyHint=true, and the description does not contradict that. It adds valuable behavioral context beyond the annotation: semantic matching over text-bearing objects, matching against names and descriptions, and returning object_id values for follow-up. It does not detail ranking or match ordering, but that is not critical for a search tool.

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 information-dense sentences with no filler. The core behavior is front-loaded, the use case is stated clearly, and the return value with next-step tool is included. Every sentence earns its place.

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 purpose, usage trigger, optional type restriction, and return value with object_id for follow-up. With no output schema, it appropriately summarizes what the agent can expect. It could mention result-order or empty-result behavior, but the description is sufficient for safe invocation.

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 baseline is 3, but the description adds real meaning beyond the schema: it clarifies that query is not just exact-match but semantic, and that type is an optional restriction. This helps the agent understand how query behaves in practice.

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 action ('Search the user's graph by matching a term against object names and descriptions') and adds the distinguishing semantic-matching behavior. This clearly separates it from sibling search tools like search_connections or search_gmail_messages by scope and mechanism.

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 says when to use the tool: to find a specific thing the user mentioned when you don't have its object_id, and even names get_graph_object as the follow-up. It does not explicitly state exclusions such as 'for browsing all objects use list_graph_objects,' but the use case is clear enough.

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