get_tf_tree

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

No annotations are provided, so the description must carry the full burden. It explains that the tool subscribes briefly to /tf and /tf_static, merges everything into a parent-child tree, and is read-only. It also notes that static transforms are latched while dynamic ones need publishing. This fairly comprehensively discloses behavior. It loses one point because it doesn't mention if it unsubscribes after the timeout or any potential blocking behavior.

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 description is well-structured with a summary line, a brief behavioral paragraph, a parameter section, and a detailed return value description. It is informative but not overly long. However, the return type description could be slightly more compact (e.g., the list of fields takes extra space). Still, every sentence earns its place. Minor deduction for lengthiness.

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?

Despite modest input schema (1 param, 0% coverage), the description is thorough. It explains the tool's behavior, the parameter semantics, the full return structure, and even includes a fallback ('empty tree means...'). The output schema exists and describes return fields, but the description adds context (e.g., what 'empty tree' means). The tool is simple (one param, one return), so the description is complete.

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?

The schema provides only one parameter (timeout) with no description. The description adds significant meaning: the default is 2.0, it's clamped to at most 10.0, and it explains the semantics of listening duration in context of static vs dynamic transforms. This adds value beyond the schema. Baseline is 4 due to 0% schema coverage, and the description fully compensates.

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 uses a specific verb 'Snapshot' and a specific resource 'the robot's TF (coordinate transform) tree'. It clearly distinguishes itself from sibling tools like 'get_topic_snapshot', 'list_topics', and 'get_camera_image' by focusing on coordinate transforms and the robot's spatial structure, not just generic topics or images.

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?

The description provides explicit guidance: it says 'Useful for spatial reasoning: which frames exist... and how they are connected.' It implies when to use (when frame hierarchy is needed) and implicitly not to use for other sensor data. It does not name alternative tools but the sibling list and the purpose make it clear it's the only tree-snapshot tool. The mention of 'Read-only — works in readonly mode' is a usage hint.

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