## Context
When the in-product AI agent guesses a tool name that doesn't exist, the
discovery tools dead-end it with no way to recover.
The most common failure is a singular/plural slip — e.g. the agent tries
`group_by_cloud_user` when the real tool is `group_by_cloud_users`
(read/bulk tools are always plural; only `find_one_*` is singular).
Today both `learn_tools` and `execute_tool` reply with a flat `Could not
find: <name>` and no suggestion, so the agent burns turns guessing or
gives up.
## Change
- Add a `findSimilarToolNames` util that ranks catalog tool names
against the missed name by Levenshtein distance (reusing the existing
`getEditDistance`), with a small bonus for a shared `<operation>_`
prefix so the correct same-operation plural is ranked first rather than
a closer-but-different operation (e.g. `find_many_person` →
`find_many_people`, not `find_one_person`).
- `learn_tools`: when names aren't found, include `suggestions` in the
structured result and inline them in the message — `Could not find:
group_by_person (did you mean: group_by_people?).`
- `execute_tool` (via `ToolRegistryService.resolveAndExecute`): append
`Did you mean: …?` to the not-found error, reusing the catalog it
already fetched (no extra lookup).
The heuristic mirrors the existing workflow variable-path suggestion
util (same edit-distance threshold), so behavior is consistent with that
prior art.
## Tests
- Unit tests for `findSimilarToolNames`: plural recovery, prefix-aware
ranking, distance threshold, 3-suggestion cap, empty catalog.
- `learn_tools` tool tests: suggestions surfaced on a miss; no
suggestion lookup when all names resolve.
`nx typecheck twenty-server` passes; `oxlint --type-aware` and `oxfmt
--check` are clean on the changed files.
https://claude.ai/code/session_01GMjZkJYkqTJogJJTM6AAV8
---
_Generated by [Claude
Code](https://claude.ai/code/session_01GMjZkJYkqTJogJJTM6AAV8)_
<!-- This is an auto-generated description by cubic. -->
<a
href="https://cubic.dev/pr/twentyhq/twenty/pull/21654?utm_source=github"
target="_blank" rel="noopener noreferrer"
data-no-image-dialog="true"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img
alt="Review in cubic"
src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>
<!-- End of auto-generated description by cubic. -->
Félix Malfait
1e8169ca3e
