docs: clarify recovery for valid lookup failures

.agents/skills/rea-tool-design/SKILL.md

@@ -13,7 +13,9 @@ documentation, and live catalogs may describe different versions.
 For provider-backed work, exercise the analyst's task through REA and compare
 relevant native provider and independent artifact observations where available.
 Check applicable partial results, recovery and session boundaries; report what
-was not exercised. Use [workflow verification](../../../docs/testing.md#provider-backed-workflow-verification)
+was not exercised. For failure guidance, follow [design recovery around the
+failure](../../../docs/tool-design.md#design-recovery-around-the-failure).
+Use [workflow verification](../../../docs/testing.md#provider-backed-workflow-verification)
 to select evidence for the proposed contract instead of seeking provider API
 parity.
 

docs/design/limits-and-recovery.md

@@ -316,8 +316,12 @@ request to change it.
   `runtime-configuration:` check. Re-run `rea setup` for that client when the
   setting is on the registration allowlist, then reconnect so the new process
   sees it.
-- `invalid_request`: correct the reported fields from the current schema or
-  CLI help. Do not repeat the unchanged call.
+- `invalid_request`: follow the specific recovery and reported issue. Inspect
+  the schema or CLI help when the input violates the contract or the response
+  asks for `inspect_input_contract`. A valid selector can instead require a
+  different choice, such as selecting a reported address; an inventory miss
+  does not establish that the target lacks the item. Do not repeat the
+  unchanged call when the response says it cannot succeed unchanged.
 
 A restart is required to adopt a changed launch environment or registration.
 The curated runtime settings above require no REA restart. It is not the first step for a transient

docs/testing.md

@@ -438,6 +438,10 @@ affected consumer.
 - Where relevant, continue after a mixed success, failed request, cancellation
   or close/reopen. Verify the next supported recovery and preservation of prior
   results and resource ownership. Use the applicable lifecycle regressions below.
+- For lookup failures, distinguish malformed input from a valid missing or
+  ambiguous selector. Check the returned candidate and input identity, follow
+  an actionable recovery where possible, and verify that an inventory miss is
+  not presented as artifact-wide absence. Test schema-repair advice separately.
 - Record the provider version, host, fixture, actual entrypoint, controlled
   faults and skipped or unavailable coverage. A simulated provider tests the
   integration boundary; a scripted sequence tests that sequence, not an agent's

docs/tool-design.md

@@ -99,6 +99,27 @@ include the smallest useful reproduction, impact and coverage limits. Do not
 claim autonomous-agent selection from a scripted trace. Check related reports
 before proposing another issue, and avoid treating lack of API parity as a bug.
 
+## Design recovery around the failure
+
+Distinguish a request that violates its input contract from a valid selection
+that the current target, provider inventory, or project cannot resolve. The
+same `invalid_request` code can represent either. Suggest schema inspection
+only when the input contract is the problem; for a valid lookup, preserve the
+caller's exact selector, the observed reason and any candidates, and give a
+next step that addresses that outcome. An inventory miss does not prove that
+the artifact lacks the requested item.
+
+Keep recovery within the selected target, provider, project and authority. If
+another context could help, describe it as an explicit choice and state any
+relevant loss of state; do not switch or select a candidate automatically.
+Preserve uncertainty, partial observations, and session or cleanup state. A
+suggested retry must be safe and explain any required change or wait.
+
+Verify recovery through the public workflow: reproduce the failure, follow
+the suggested next step when feasible, and check the result and session state.
+Include a malformed-input control so schema guidance remains available when it
+is actually needed. Compare CLI and MCP when both expose the operation.
+
 ## Define the contract
 
 - Use strict inputs with explicit target identity and required fields. Preserve