Skip to main content
Glama
io.github.xngg1021/academic-research-kernel

io.github.xngg1021/academic-research-kernel

by xngg1021

research_artifact_ingest

Ingest a scholarly artifact envelope into kernel state to update research objects, claim-evidence graphs, and the ledger. Preview deterministic ingestion with dry-run before committing.

Instructions

Deterministically ingest a scholarly artifact envelope into kernel state (ResearchObjects, CEG, and Ledger).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "envelope": "<envelope>"
    },
    "name": "research_artifact_ingest"
  }
}

Input Schema

NameRequiredDescriptionDefault
stateNoOptional initial kernel state snapshot (containing 'ceg', 'ledger', 'objects').
dry_runNoIf true, simulates ingestion and returns plan without committing state.
bindingsNoOptional explicit bindings (e.g. {'decision_id': '...', 'claim_id': '...'}).
envelopeYesThe ResearchArtifactEnvelope to ingest.
content_payloadsNoAuthorized base64 content by lineage entity ID; maximum total 10 MiB.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full behavioral burden. It does disclose that ingestion is deterministic and mutates kernel state across three subsystems, but says nothing about idempotency, conflict handling, authorization requirements implied by 'Authorized base64 content', or what happens when the envelope is invalid.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence with no filler, naming the action, input, and state targets. It is efficient but sits at the edge of under-specification for a five-parameter mutation tool with nested envelope and bindings objects.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and no output schema, the description should explain what a successful ingest returns (a receipt? ledger entry? plan when dry_run is true) and how failures surface. For a state-committing tool with nested objects, the single sentence leaves an agent unable to predict the result or safe invocation pattern.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters including dry_run, bindings, and content_payloads are already documented in the schema. The description adds no syntax, format, or selection guidance beyond that, and the 10 MiB payload cap is already in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (ingest) and resource (scholarly artifact envelope) plus the three destinations it writes to (ResearchObjects, CEG, Ledger). That is far more concrete than the sibling names alone imply, though it never explicitly contrasts itself with research_artifact_validate, which an agent must distinguish it from.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no preconditions (e.g. validate first), and no mention of when not to call it. The word 'ingest' implies a commit step following validation, but that ordering is left entirely to inference across a 17-tool sibling set.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.