resolve

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and network reach are covered. The description adds useful disclosure of the returned payload (last modified by whom, sheets with used ranges), which is beyond the annotations. It does not say what happens when an alias is unknown or the file is unreachable, leaving failure behavior opaque.

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?

One economical sentence with no filler, front-loaded with 'Workbook info'. It is a telegraphic fragment rather than a complete sentence, which slightly reduces readability but wastes no space.

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?

There is no output schema, so the description correctly carries the burden of describing return values, and it does so at a useful level of detail. What is missing is failure/error semantics for unresolvable inputs, which matters for an open-world read tool, but the core need to call it correctly is met.

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?

With a single parameter at 100% schema description coverage, the schema already explains the accepted forms (SharePoint URL, alias from ~/.graph-excel/workbooks.json, or driveId:itemId). The description adds nothing about the 'file' argument, so the baseline 3 applies.

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 concretely what the tool returns: workbook identity (driveId/itemId), last-modified metadata with author, and every sheet with its used range. That distinguishes it from siblings like read_range or find, which deal in cell contents. It reads as an output inventory rather than a verb+resource, and the name 'resolve' alone would be opaque, but the description disambiguates it.

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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. An agent must infer that this is the entry point for turning a URL/alias into IDs and sheet names before calling read_range or write_values. The schema's mention of aliases hints at that role but the description never says it.

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