td_capture_frame

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

Describes that base64 image is only returned conditionally (confirm=True or save_path), save_path overrides confirm, and token cost is near-zero by default. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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?

Well-structured with front-loaded purpose. Every sentence adds essential information without redundancy. Two clear paragraphs covering behavior, token cost, and alternatives.

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?

Given the tool's complexity (4 params, output schema exists), the description covers the key behavioral aspects: token cost, conditional returns, disk writing, and usage preferences. Nothing missing for effective agent usage.

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?

Adds substantial meaning beyond schema: explains conditional gating of base64 return, token cost implications, and save_path's role in overriding confirm and writing to disk. Schema coverage is 100%, but description provides critical behavioral context.

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 clearly states the tool captures a single frame from a TOP node with a metadata-first approach. It distinguishes itself from siblings by name-dropping td_screenshot and td_capture_and_analyze with specific use cases.

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?

Provides explicit guidance on when to use alternatives (td_screenshot for inline thumbnail, td_capture_and_analyze for cooking state/errors) and advises asking user before setting confirm=True due to token cost.

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