docs: canonical identifier map (which tool expects which id)

[mocha06]

Motivation

Closes #390.

Pipefy exposes several identifier forms — slug, internal_id, uuid, numeric id — and different tools expect different ones. The guidance was scattered across per-area docs and skills with no single source of truth, so agents learned which id each tool wants by trial and error (wrong-id errors, extra round-trips). The sharpest traps: the same pipe is addressed by five different argument names (pipe_id, repo_id, source_repo_id, repo_uuid, pipe_uuid) in two different forms, and a handful of *_uuid arguments also accept a numeric id.

Outcome

Adds docs/mcp/tools/identifiers.md: a canonical map keyed on tool/argument, covering the four forms, the five names for a pipe side by side, the UUID-named-accepts-numeric exceptions, the field-reference slug-vs-internal_id rule, and a per-area quick reference.

The map is wired in as the single source of truth: the docs index and the cross-cutting IDs section now point at it, AGENTS.md lists it, and the per-area Identifiers subsections (observability, knowledge-bases, llm-providers, portal), the pipes-and-cards and automations discussions, and the identifier-heavy skills link to it rather than each keeping a partial list.

Documentation only — no tool or CLI behavior changes.

[adriannoes]

The canonical map is the right shape for #390 and the wiring (index, AGENTS, area docs, skills, deep-links) looks solid. One accuracy gap should land before merge.

Required before merge

The UUID-named-accepts-numeric section (and the Observability quick reference) currently omit that get_agents_usage and get_automations_usage also accept a numeric organization id via the same resolve_organization_uuid path as credits and portals. Shipping a false "everywhere else wants a UUID" claim undercuts the SSOT. See the inline on identifiers.md.

Also noted

• Observability skill Identifiers table still says org usage wants organization_id (numeric) under the new SSOT deep-link. Usage tools take organization_uuid (UUID or numeric). Pre-existing row; worth fixing in this PR since the file was touched.
• Five-names pipe_uuid Where cell says "knowledge-base tools" only; report reads / audit export also take pipe_uuid while create/export stay on numeric pipe_id. Optional polish, not a merge gate.

What worked well

Clear SSOT structure (four forms, five pipe names, field slug vs internal_id), stable section anchors after the and renames, and systematic deep-links instead of file-top only.

[adriannoes]

The new UUID-named-accepts-numeric section lists only get_ai_credit_usage, list_portals, and create_portal, then says everywhere else *_uuid wants a UUID. That is not true for get_agents_usage and get_automations_usage: both MCP Args say "Organization UUID, or numeric organization id", and the SDK resolves via resolve_organization_uuid (same path as credits and portals). The Observability quick reference compounds it by calling usage tools UUID-only and carving out only credits.

I would add those two usage tools to this list (or group as all three observability usage tools) and reword the Observability bullet so usage matches credits: UUID or numeric under organization_uuid. Soften or drop the absolute "Everywhere else" sentence once the list is complete.

Done when:

• This section lists get_agents_usage and get_automations_usage (or an equivalent grouping)
• Observability QR no longer paints usage as UUID-only while only credits accept numeric
• A quick skim of resolve_organization_uuid callers matches the exception list

Suggested change

	A few arguments are named `*_uuid` but the API resolves a numeric id too. Prefer the UUID; a numeric id is a documented fallback:
	- `get_ai_credit_usage(organization_uuid)`
	- `list_portals(organization_uuid)`, `create_portal(organization_uuid)`
	Everywhere else, an argument named `*_uuid` wants a UUID and an argument named `*_id` wants a numeric id.
	A few arguments are named `*_uuid` but the API resolves a numeric id too. Prefer the UUID; a numeric id is a documented fallback:
	- `get_ai_credit_usage(organization_uuid)`, `get_agents_usage(organization_uuid)`, `get_automations_usage(organization_uuid)`
	- `list_portals(organization_uuid)`, `create_portal(organization_uuid)`
	For these, prefer the UUID. Elsewhere, an argument named `*_uuid` wants a UUID and an argument named `*_id` wants a numeric id.

[mocha06]

Thanks @adriannoes — verified all three against the code and applied in fe252b9.

✅ Required — usage tools accept numeric org id. Confirmed against ground truth: get_agents_usage, get_automations_usage, and get_ai_credit_usage all take organization_uuid and all resolve via resolve_organization_uuid (which accepts a UUID or a numeric id), and their MCP docstrings say "Organization UUID, or numeric organization id." So my carve-out of only credits was wrong. Fixed:

• The UUID-named-accepts-numeric section now lists all three usage tools (grouped) plus portals, and drops the absolute "everywhere else" phrasing.
• The identifiers.md Observability quick reference now says the usage tools take UUID or numeric, and only metrics (get_automation_execution_metrics) / export (export_automation_jobs) are numeric organization_id-only.

✅ Also noted (a) — observability skill row. Fixed the Identifiers table row: usage stats take organization_uuid (UUID or numeric), not numeric organization_id. While there, I also corrected the same inaccuracy in observability.md itself (the "usage queries" row and the two tool-table rows said "org UUID"/"Requires org UUID") since that file is touched by this PR and would otherwise contradict the SSOT.

✅ Also noted (b) — pipe_uuid beyond KB. Confirmed report_tools.py — the pipe report reads (get_pipe_report*) take pipe_uuid; report create/update use numeric pipe_id. Broadened the five-names pipe_uuid cell accordingly. (I couldn't find an audit-export tool that takes pipe_uuid — no audit_tools declares it — so I left that out rather than assert it.)

Anchors still resolve, skills-ref lint green.

[adriannoes]

Thanks for the follow-up. The usage-tool UUID-or-numeric exception list, Observability quick reference, area guide, and observability skill row now match the MCP Args / resolve_organization_uuid path. The pipe_uuid Where note for report reads is a welcome polish too.

Looks good to merge from my side.