Veynod

Agent Claim And Read

agent_claim_and_read

Claim a READY/HANDOFF task with a TTL lease and load its L1 context.

``context`` holds the task's context_docs at their pinned versions, the
latest continuation pack first (is_continuation: true): read it before
anything else. Untrusted bodies come as untrusted_content.

Returns the task, upstream L1 handoff briefs, referenced state slots and
document summaries. L2 artifact bodies are intentionally not included;
call dereference(artifact_uri) only when verification is required.
The response's lease carries lease_id, fencing_token and
heartbeat_interval_s: call heartbeat(lease_id) on that interval and pass
fencing_token with your task writes.

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": {
      "task_key": "<task_key>"
    },
    "name": "agent_claim_and_read"
  }
}

Input Schema

Name	Required	Description
`agent`	No
`task_key`	Yes
`lease_seconds`	No	Legacy lease TTL in seconds (5–3600). Prefer lease_ttl_seconds.
`idempotency_key`	No	Optional. Retries with the same key and arguments within 24 h replay the first result (replayed=true) without a second write; a different body with the same key is idempotency_key_reused.
`include_context`	No
`session_batch_id`	No
`context_max_bytes`	No
`lease_ttl_seconds`	No	Lease TTL, 60–3600 s (default 900 under API 2026-11, 900 before). Heartbeat every lease.heartbeat_interval_s or the task returns to READY.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 3, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond by disclosing the lease/TTL mechanics, the fencing_token requirement for writes, the READY reversion on missed heartbeats, and the untrusted_content marking for unsafe bodies. It is strong on operational consequences, though it never states what happens on a claim conflict (already-claimed task) or whether a failed claim is a no-op.

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?

Front-loaded with the core action, then progressively adds the context-reading order, the exclusion of L2 bodies, and the lease obligations. Dense but every paragraph carries operational information; only the explicit return-value enumeration slightly duplicates what the output schema already covers.

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

Completeness4/5

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

For a mutating claim-and-load operation with 8 parameters, the description covers the essential mechanics: what gets loaded, what is withheld, and what the caller must do afterward. With an output schema present, return-shape explanation is a bonus rather than a requirement, so the remaining gap is mainly the unaddressed optional parameters and conflict behavior.

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 only 38% across 8 parameters, so the description carries more burden than it meets: it explains the lease concept but never mentions include_context, context_max_bytes, agent, session_batch_id, or the lease_seconds vs lease_ttl_seconds legacy/preferred split. It adds real meaning for the lease and context concepts but leaves several parameters undocumented in both places.

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

Purpose5/5

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

States a specific verb and resource with scope: "Claim a READY/HANDOFF task with a TTL lease and load its L1 context." The state qualifier (READY/HANDOFF) and the L1 context load together distinguish it clearly from siblings like list_tasks, acquire_resource, or agent_handoff_task.

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

Usage Guidelines4/5

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

Explicit guidance downstream of the call: read the continuation pack first, call dereference(artifact_uri) only when verification is required, and heartbeat(lease_id) at the returned interval. It does not, however, say when to choose this over alternatives such as list_tasks scanning or agent_handoff_task, so the when-not-this-tool axis is missing.

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

All Veynod tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.