KeeperHub / KeeperHub/keeperhub
docs: execute_transfer/execute_contract_call's simulate response has no documented schema
- 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
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