Skip to content

Add ai_tool object to the ai_operation profile for MCP primitive metadata - #1729

Open
Levaj2000 wants to merge 2 commits into
ocsf:mainfrom
Levaj2000:issue-1728-v2
Open

Add ai_tool object to the ai_operation profile for MCP primitive metadata#1729
Levaj2000 wants to merge 2 commits into
ocsf:mainfrom
Levaj2000:issue-1728-v2

Conversation

@Levaj2000

Copy link
Copy Markdown
Contributor

Related Issue:

#1728

Description of changes:

Adds a new ai_tool object (extending _entity), referenced optionally from the ai_operation profile, recording the AI capability invoked in an operation — full rationale, field-by-field justification, and open questions are in #1728 (proposed by @terylt and @Levaj2000):

  • objects/ai_tool.json (new): primitive kind (type_id: Tool/Resource/Prompt), stable capability identity (uid) vs. call correlation (transaction_uid), provenance (service + transport_id), binding (source_id: MCP/Function/Built-in), declared MCP behavior hints (is_readonly/is_destructive/is_idempotent/is_open_world — descriptions state they are self-declared and unverified), schema fingerprints reusing the fingerprint object, resource fields (uri, mime_type), and MCP 2026-07-28 RC fields (cache_scope_id, cache_ttl, task_uid).
  • profiles/ai_operation.json: adds the optional ai_tool attribute, with guidance that observed behavior wins over declared hints when deriving activity_id.
  • dictionary.json: 12 new entries (ai_tool, transport/transport_id, is_destructive, is_idempotent, is_open_world, input_schema_fingerprint, output_schema_fingerprint, cache_scope/cache_scope_id, cache_ttl, task_uid); everything else reuses existing dictionary entries.
  • CHANGELOG.md: entries under Unreleased → Added → Profiles / Objects / Dictionary Attributes.

Single squashed commit authored by @terylt, co-authored by @Levaj2000, DCO signed-off by both.

Validation status (why this opens as draft): all three changed schema files parse as valid JSON and the diff applies cleanly to current main; a local ocsf-server run has not yet been performed — we'll do that (or lean on CI) before marking ready for review.


Generated by Claude Code

…data

Adds a new ai_tool object (extending _entity) referenced optionally from
the ai_operation profile, recording the AI capability invoked in an
operation: primitive kind (tool/resource/prompt), stable capability
identity, provenance (serving service + transport binding), declared
MCP behavior hints (explicitly self-declared and unverified), and
input/output schema fingerprints for contract-drift detection.

Closes ocsf#1728. Verified against main with a local JSON parse of all
three changed files; dictionary additions reuse existing entries where
they exist (name, uid, namespace, service, fingerprint, uri, mime_type,
version, is_readonly, transaction_uid, source/source_id).

Signed-off-by: Teryl Taylor <terylt@ibm.com>
Signed-off-by: Jeff Leva <120221487+Levaj2000@users.noreply.github.com>
Co-authored-by: Jeff Leva <120221487+Levaj2000@users.noreply.github.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VbzWjrF29ixcTwVvpR8ntg
@github-actions

github-actions Bot commented Aug 13, 2026

Copy link
Copy Markdown

Schema Description Review

Automated suggestions for improving description clarity for LLM consumption. These are advisory — not required changes.

Previous Review Status

  • Fixed: type — the In the case of 'Other', it is defined by the event source. clause has been added.
  • Fixed: source_id — the In the case of 'Other', it is defined by the event source and carried by the <code>source</code> attribute. clause has been added.
  • Fixed: CHANGELOG entries now use PR links (pull/1729) rather than issue links.

Summary

All three issues from the previous review have been addressed. The ai_tool object is well-structured, descriptions are detailed and LLM-friendly, sibling conventions are correctly followed, and the CHANGELOG entries now reference the correct PR URL. No new issues have been introduced.

✅ No description issues found — descriptions look clear for LLM consumption.

Per the schema description review: add the standard 'Other' clause to
the type sibling, and the 'Other'/source-sibling note to source_id.
Swap the three CHANGELOG references from issue ocsf#1728 to this PR, per
the changelog convention.

Signed-off-by: Jeff Leva <120221487+Levaj2000@users.noreply.github.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VbzWjrF29ixcTwVvpR8ntg
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants