get_metadata

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

With no annotations, the description carries the burden and largely meets it: it discloses the XML output format, the default behavior when nodeId is omitted (returns pages and saved snapshots), and the injected 'Currently selected nodes:' block when a selection exists. It does not discuss result size limits or permission requirements, which is a modest omission for a read-only 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?

The routing warning is front-loaded ahead of the functional description, which is the right order for an agent deciding between tools. Sentences are dense and mostly earn their place, though the parenthetical page-id example slightly overlaps with schema documentation.

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 and no annotations, the description must convey the return shape, and it does reasonably well: XML structure, field set, page-mode fallback, and the selection block. It stops short of noting what it deliberately omits (styles, variables, text content), which would help an agent decide against 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: nodeId may be a page id (e.g. 0:1), and omitting nodeId returns the document's pages rather than merely 'using the current selection' as the schema states. It also clarifies that fileKey is accepted for compatibility only and the desktop file is always used.

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 metadata for a node or page'), names the exact output format (XML), and enumerates the fields returned (node IDs, layer types, names, positions, sizes). It also explicitly positions itself against the sibling get_design_context, so an agent can distinguish it without opening 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?

It names the alternative (get_design_context) and strongly deprioritizes itself with 'Always prefer to use get_design_context.' The implied use case ('useful for an overview of the structure') gives context, but it never states the positive condition under which this tool is the right pick, so it falls short of the full when/when-not/alternatives bar.

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