KeeperHub / KeeperHub/keeperhub

docs: execute_transfer/execute_contract_call's simulate response has no documented schema

Open Beginner friendly
#2,488 2 comments 0 reactions 0 assignees View on GitHub
accepted confirmed documentation
Dominant language
TypeScript
Stars
24
Forks
93
Avg merge
1d 8h
Merged PRs (30d)
266

Description

### Page

`tools_documentation`'s "DIRECT EXECUTION (EVM WRITES)" section, and the `execute_transfer`/`execute_contract_call`/`execute_check_and_execute` tool schemas themselves (MCP `tools/list`).

### Reason: what the page says

`tools_documentation` describes the simulate step only as: "Continue only after success=true and wouldRevert=false; any tool error is a hard stop." The three tools' own JSON schemas document their *input* parameters only — none of the three has any `output`/`returns` schema, so there is no documented shape for what a `simulate: true` call actually returns.

### Reason: what the code does

A real `simulate: true` call against `execute_transfer` (and, checked separately, `execute_contract_call`) returns a real gas estimate under the key `gasEstimate`:

```
$ execute_transfer(chain_id: "84532", to_address: "0x...", amount: "0.000001", simulate: true)

{
"success": true,
"status": "simulated",
"from": "0x9219ab85...",
"to": "0xDeaDbeef...",
"value": "1000000000000",
"gasEstimate": "21000",
"simulatedReturnValue": null,
"wouldRevert": false
}
```

Reproduced today (2026-09-15) against production for both `execute_transfer` and `execute_contract_call` — both use `gasEstimate`, consistently. This isn't a cross-tool inconsistency; it's that the field name (and the rest of the response shape: `status`, `from`, `to`, `value`, `simulatedReturnValue`, `wouldRevert`) is not documented anywhere a caller can read before making the call. An integrator has to make the call once, in production, to learn the shape — which is a bad first experience for a value-moving API, even though nothing here is a bug (the behavior is correct and consistent).

### Scope: where else this appears

Checked `execute_transfer` and `execute_contract_call`'s simulate responses directly — both match. Did not check `execute_check_and_execute`'s "condition met, action simulated" response field-for-field against this shape, though I believe (from earlier testing, not re-verified for this issue) it also uses `gasEstimate`. This is one problem: the direct-execution family's response schema is undocumented, not that any specific tool's response is wrong.

### Plan: which one changes

The docs - the code is behaving correctly (the shape is real and consistent; it just isn't written down).

### Plan: the correction

Add an output/response schema (or a documented example, at minimum) for the `simulate: true` response shape to `execute_transfer`, `execute_contract_call`, and `execute_check_and_execute`'s tool descriptions or `tools_documentation`, naming at least `success`, `status`, `gasEstimate`, `simulatedReturnValue`, and `wouldRevert`. This costs nothing to existing callers (no shape change) and turns "call it once to find out" into something readable from the schema alone, matching how the input side is already documented.

Contributor guide

Open the contributing guide

Research direction

Start with the tools_documentation "DIRECT EXECUTION (EVM WRITES)" section and the MCP tools/list descriptions for execute_transfer, execute_contract_call, and execute_check_and_execute. Document the simulate response schema, including success, status, gasEstimate, simulatedReturnValue, and wouldRevert, and ensure the three tool descriptions or the shared documentation show the response shape.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.