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

With only readOnlyHint=true in the annotations and no output schema, the description carries the return-shape burden and does it well: enumerates {found, object, fields, editable_fields, connected_objects, connected_total} and explains the no-match contract (found=false with searched_for, plus matches on ambiguous names). That is exactly the behavior an agent needs to branch on.

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, front-loaded with purpose, then identification rules, then return shape. No filler; each clause (edge examples, preferred id, not-found fields) adds distinct 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?

Covers purpose, identification, return structure and empty-result behavior for a read-only 2-param tool. The remaining gap is the both-optional parameter situation (neither given, or name and object_id disagreeing), which is left unspecified.

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; the description goes beyond by stating object_id is 'exact and preferred' and is the value returned by search/list, which gives precedence guidance the schema lacks. It does not say what happens when both or neither parameter is supplied, despite zero required params.

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 ('Get one object from the user's graph') plus the defining scope differentiator — it returns the object together with its connected objects/edges. That adjacency payload distinguishes it from sibling search_graph_objects and list_graph_objects without the agent needing to open either schema.

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?

Gives explicit triggering conditions: 'when the user asks about a specific thing in their graph, or to follow a connection you found on another object', and hints that search/list produce the object_id this tool wants. It does not name the alternative tools directly or state when not to use it (e.g. broad lookups should go to search_graph_objects).

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