embodify-mcp

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

With no annotations provided, the description carries the full burden and does so well: it discloses side-effect-free behavior ('Renders no images and uses no step budget'), availability at any lifecycle point, and the idle-vs-running state differences (no task/state while idle, default_scene returned instead). It also explains task_locked semantics, which an agent could not infer elsewhere.

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-loaded with purpose then constraints, and every sentence adds usable information. The dense return-field enumeration is long but each element (eef_pos_m units, gripper fields) earns its place for an agent with no output schema.

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, so the description must carry the return contract, and it fully enumerates run, status, step, max_steps, steps_left, task, task_locked, and state including units. Combined with the idle-state caveat, an agent has everything needed to call and interpret this tool.

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 tool takes zero parameters, so the baseline is 4. The description instead documents the rich return shape, which is useful but not a parameter concern.

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+resource ('Read the state of the current run') and immediately enumerates the scope (task context, instruction, step count, robot state). It explicitly distinguishes itself from the sibling list_tasks, so an agent can route correctly without opening a 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?

Gives explicit when-to-use conditions ('callable at any time, including before the first reset_task') and names the alternative for a different need ('To see which tasks are available, use list_tasks'). This is unambiguous routing guidance.

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

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

With no annotations present, the description carries the full burden and does so: it discloses that the call is independent of the current run, renders no images, consumes no step budget, and does not alter a running episode. These are exactly the side-effect and cost traits an agent needs before calling in an interactive simulation.

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 most important constraint (independent of the current run) and then organizes the rest by mode, with no filler sentences. Slightly dense and could be tightened, but every sentence carries information.

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?

There is no output schema, so the description correctly documents return contents for both modes (suites and counts; task_index, instruction, n_init_states) and explains n_init_states inline. An agent has everything needed to call it and interpret the result.

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 goes further by spelling out what omitting 'suite' yields (suite names, per-suite task counts, total) versus what passing it yields (task_index, instruction, n_init_states). That is meaningful added semantics, though it does not cover type/format constraints.

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+resource ('List the tasks FakeSim offers') and immediately distinguishes the two invocation modes (no argument = suite overview; with suite = per-task detail). It is clearly separable from siblings like reset_task and observe.

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?

Gives an explicit workflow: 'Start here, pick a suite, then look inside it' and 'Pass the chosen suite and task_index to reset_task to start.' It names the downstream tool and the condition that selects it, leaving nothing to inference.

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

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

With no annotations, the description carries the full burden and does so: it discloses best-effort motion, P-control stepping, the four stop conditions with their meanings, the budget exhaustion path (only stop_episode afterwards), and the step_limit error when budget is 0. These are exactly the non-obvious behaviors an agent needs before calling.

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 long but information-dense and front-loaded: the core motion semantics come first, then the stop reasons, then the return payload. The stop-reason list is the one section that could be tightened, but every item carries decision-relevant content.

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?

For a 2-parameter motion tool with no output schema and no annotations, the description covers frame conventions, units, failure modes, continuation strategy, and the full return payload (images, state, action fields, step, steps_left, status). Nothing an agent needs to call it correctly is 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 coverage is 100% so the baseline is 3, but the description adds real meaning beyond the schema: the world frame with z up, the table surface at z=0.80 m, that delta_rpy rotates about the robot base X/Y/Z axes in radians, and that omitted delta_rpy keeps the current orientation.

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: move the end effector by delta_xyz meters in a named frame, with optional delta_rpy rotation. This is clearly distinct from siblings like set_gripper, observe, or stop_episode, so an agent can select it without ambiguity.

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?

Gives strong operational guidance: how to interpret each stop_reason, that 'stalled' means repeating the same command has no effect and the agent should change direction or lift first, and that 'step_cap' should be followed by another call with the remaining displacement. It doesn't explicitly frame when to prefer another tool, but the conditions are clear.

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

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

No annotations are provided, so the description carries the full burden. It discloses the key behavioral traits: it does not advance the simulation and does not consume the step budget, and it enumerates the exact return fields with units. It does not cover error conditions or permissions, but for a non-mutating observation tool this is largely adequate.

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?

It is a single dense sentence but front-loads purpose before listing returns; every clause provides useful information. It could be slightly more scannable, but there is no filler or repetition.

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 fully documents the return shape (two labeled PNG images, state fields with units, step counters, status) and the side-effect profile, leaving no significant gap for an agent invoking this zero-parameter read tool.

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 tool takes zero parameters, so the baseline is 4. There are no parameters to clarify and the description appropriately focuses on outputs instead.

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 (Read) and resource (current RGB images and end-effector/gripper state) and adds the crucial scope constraint 'without advancing the simulation or using the step budget,' which sharply distinguishes it from the actuation siblings like move_relative and set_gripper.

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 'without advancing the simulation' clause implies when to use it (inspection without stepping), but it never names an alternative or says when not to use it. Sibling get_session_info is not mentioned as a differentiating option.

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

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

No annotations exist, so the description carries the full burden and does so: it discloses two distinct failure modes (task_locked, already_running), the precondition that stop_episode must precede it, default-argument behavior, and the full shape of the return payload. This is far beyond what a bare 'reset' would convey.

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 most important fact — that all three arguments are optional and omitting them is the common path — is bolded and front-loaded, which is well judged. The trailing enumeration of the return payload is long and reads as a run-on, but it is justified because no output schema exists.

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 annotations and no output schema, the description must supply safety, preconditions, error behavior, and return semantics on its own — and it does all four, including unit-bearing field explanations (eef_pos_m, eef_rpy_rad, gripper.opening_m). Nothing an agent needs to call this correctly is 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 100%, so the schema already documents suite, task_index, and init_state_index including their defaults and the n_init_states bound. The description largely restates that ('init_state_index picks another object layout', task 0 default) rather than adding new syntax or constraints, so the baseline 3 applies.

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?

Opens with a specific verb and resource ('Start a new FakeSim episode') and immediately clarifies the scope of the operation (fresh episode, not a continuation). An agent can distinguish it from stop_episode, observe, and get_session_info without opening any 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?

Explicit routing: omit all args for the default scene, call list_tasks first to switch tasks (and it even explains what list_tasks returns with and without args), and call stop_episode first if an episode is already running. The --lock-task precondition is stated as a when-not condition.

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

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

With no annotations, the description carries the full load and does so exceptionally: it explains the adaptive stop algorithm, that 'settled' does not imply a firm grasp or released object, the no_op case, the budget-exhaustion lockout, and the step_limit error leaving the target unchanged. This is exactly the operational context an agent needs for a stateful actuator.

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 first sentence front-loads purpose plus the key behavioral mechanic, then the four stop reasons are cleanly bulleted. Length is justified because it simultaneously serves as the missing output documentation (no output schema exists); every clause is load-bearing.

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 annotations and no output schema mean the description must cover both behavior and returns, and it does: it enumerates the returned fields (images, state, action, step, steps_left, status) with units and meanings, plus the error path. Nothing an agent needs to call or interpret this tool correctly is 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 coverage is 0% and there is one parameter, but its enum values open/close are self-explanatory. The description never names or explains the 'state' parameter directly, and its references to 'the requested gripper target' do not map cleanly onto a parameter called state, so compensation for the coverage gap is only partial.

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?

"Open or close the gripper" is a precise verb+resource that an agent can act on immediately, and the gripper is a domain no sibling tool (move_relative, observe, stop_episode) touches. It stops short of explicitly positioning itself against those siblings, but the resource is unmistakable.

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 stop_reason breakdown effectively tells the agent what to do next: repeat the same command on step_cap, and note that only stop_episode is callable once budget is exhausted. That is concrete downstream guidance, though it never states the motivating use case (e.g. grasp vs release) or a when-not-to-use condition.

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

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

With no annotations, the description carries the full burden and actually discloses meaningful side effects: frames, event log and summary are persisted, and it enumerates the returned run ID, status and artifact paths. It does not state preconditions (must an episode be active?) or error behavior, which a terminal state-changing tool should ideally cover.

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?

Two tightly written sentences: the action is front-loaded and the second sentence enumerates return fields with parenthetical formats (events.jsonl path, PNG frame directory, summary.json path). Every clause carries information, with no filler.

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?

There is no output schema, so the description usefully documents the return shape itself (run, status, artifacts with paths), which makes it reasonably self-sufficient. It falls short only on lifecycle preconditions and what happens if no episode is running, which matter for a terminal operation in a stateful simulation.

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 tool takes zero parameters, so the schema imposes no semantic burden and the baseline of 4 applies. Nothing in the description contradicts or obscures the empty parameter set.

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 states a concrete verb and resource ('End the current simulation and save its frames, event log and summary'), so the agent knows exactly what happens. It is distinguishable from siblings like observe or move_relative, though it never explicitly contrasts with reset_task, which is the closest ambiguous alternative.

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?

Usage is only implied: 'End the current simulation' suggests calling it to wrap up an episode, but there is no explicit when-to-use, no when-not-to-use, and no guidance on how it relates to reset_task in the sibling set. An agent must infer the workflow position.

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