get_joint_config

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It fully does so by explaining the return data, the units (per-radian vs per-meter, and the USD per-degree conversion warning), and the fact that it's a diagnostic tool (implying read-only). The explicit warning about the 57.3x stiffness error is a significant behavioral detail that prevents silent failures. No contradictions with annotations (since none exist).

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 and every sentence serves a purpose. It opens with a one-line definition, lists the returned fields, then gives three 'call when' conditions, followed by a crucial units caveat and the parameter explanation. There is no fluff or redundant content; it is appropriately detailed without being verbose.

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 simplicity (one parameter) and the presence of an output schema (which presumably defines the return structure), the description is complete. It covers what the tool does, when to use it, the units, and the parameter semantics. Nothing an agent needs to invoke it correctly is missing. The diagnostic nature and read-only implication are clear, making this a fully self-sufficient description.

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 input schema has one parameter (prim_path) with no description in the schema (coverage 0%). The tool description compensates fully by stating it is the 'USD path to the robot articulation root.' This is sufficient for a single, self-explanatory parameter, and the description adds the necessary context for correct invocation.

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's function: a diagnostic tool that retrieves joint drive configuration (stiffness, damping, limits, target vs actual positions, position error) for a robot articulation. It uses a specific verb and resource, making it distinct from sibling tools like get_joint_positions or set_joint_positions. The diagnostic focus and explicit return values leave no ambiguity about purpose.

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, scenario-based guidance for when to use this tool: when joint drives aren't tracking targets, when joints oscillate or are unstable, and when joints hit limits unexpectedly. It also gives a practical caveat about writing gains back via execute_script, which helps agents avoid misuse. This is clear and actionable, distinguishing it from alternatives.

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