get_surface_annotations

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, not open-world), and the description adds substantial context beyond them: it includes hidden objects/overlays, unsaved edits, works with no viewport, each page is a fresh read, and requires Blender running with FacetCue enabled. This is a genuine auth prerequisite and coverage disclosure.

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?

Front-loads the core action and return summary, then layers prerequisites and pagination. Dense but every clause carries information; the 'no selection, saving, Python code or screenshot is required' list is slightly flourishy but clarifies a common agent assumption.

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?

No output schema exists, and the description covers the return shape well (full notes, stable IDs, 3D positions, anchor validity, visibility), plus prerequisites and pagination. Nothing an agent needs to call this correctly appears to be 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?

Schema description coverage is 0%, so the description must compensate, and it largely does: scene_name narrows the file, limit is 1..200, include_visibility=false gives a lighter read, and pagination follows next_offset. It never directly explains the offset parameter's meaning, leaving one small gap.

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 ('Read user surface marks/TODOs from the current Blender file') with clear scope. It does not explicitly name or contrast with its only sibling submit_annotation_changes, though the read-vs-write distinction is inferable. Clear purpose but no explicit sibling differentiation.

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 instructs 'Call with no arguments first' and gives conditions for optional narrowing ('scene_name optionally narrows the file') and a lighter read ('include_visibility=false'). No explicit when-not guidance or named alternative, but the usage context is clear.

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