home / skills / bdambrosio / cognitive_workbench / mc-observe-items

mc-observe-items skill

safe

This skill observes visible item entities within a fixed radius, filtering by forward cone and line-of-sight to help inventory planning.

npx playbooks add skill bdambrosio/cognitive_workbench --skill mc-observe-items

Review the files below or copy the command above to add this skill to your agents.

Files (2)

Skill.md

2.3 KB

---
name: mc-observe-items
type: python
description: "Visible item entities within radius R (default/max 7), filtered by forward cone and line-of-sight."
---

# Minecraft Observe Items Tool

Enumerates all visible item entities (dropped items) within observation radius. Provides structured summary with pose, item counts, nearest items, and pickup affordances.

## Purpose

Visible item observation for inventory management and item collection planning. Returns both human-readable SUMMARY text and machine-readable structured data.

## Input

- `radius`: Optional integer observation radius (default: `7`, max: `7`)
- `entities_radius`: Optional integer observation radius (default: `7`, max: `7`). If both provided, `entities_radius` takes precedence.
- `value`: Ignored

## Output

Returns uniform_return format with:
- `value`: Multi-line SUMMARY text (human-readable, ≤ 1024 chars)
- `data`: Structured observation dict (machine-readable). Key fields:
  - `success`: Boolean
  - `pose`: `{x, y, z, yaw, pitch}` (floats)
  - `items`: `{total: int, types: {string: int}, nearest: {string: float}, by_distance: [dict], nearby: [dict]}`
    - Each entry in `items.nearby` includes: `name`, `type`, `position`, `dx`, `dy`, `dz`, `distance`, `item_name`, `item_count`
  - `pickup`: `{in_range: [string], nearby: [string], far: [string]}`
  - `conf`: `"high"` | `"med"` | `"low"`
  - `note`: String (human-readable summary)

## Behavior & Performance

- Enumerates visible item entities within radius, filtered by view cone (yaw ±60°, pitch -60..+90) and line-of-sight
- Radius limits: Default 7 blocks, maximum 7 blocks
- Confidence levels: `high` (complete, fast), `med` (complete but slow/many items), `low` (incomplete observation)
- Pickup affordances: Categorizes items by pickup range (in_range, nearby, far)

## Guidelines

- Use `mc-observe-blocks` for block observation (this tool only reports item entities)
- `pickup.in_range` indicates items that can be picked up immediately
- `conf=low` indicates incomplete observation - may need retry or larger radius
- Raw data stored in `data.items.nearby` for detailed analysis

## Usage Examples

Standard observation:
```json
{"type":"mc-observe-items","out":"$items"}
```

With custom radius:
```json
{"type":"mc-observe-items","radius":7,"out":"$items"}
```

Overview

This skill detects visible dropped item entities around the player within a configurable radius (default and maximum 7 blocks). It produces both a concise human-readable SUMMARY and a structured data object detailing pose, item counts, distances, and pickup affordances. Use it to plan collection, manage nearby loot, or feed automated agents with precise item data.

How this skill works

The tool scans for item entities within the observation radius, then filters results by a forward view cone (yaw ±60°, pitch -60° to +90°) and line-of-sight so only visible items are reported. It returns a structured payload that includes the observer pose, total counts grouped by item type, nearest items, a by-distance list, and pickup-range categories. Confidence flags indicate completeness and performance trade-offs.

When to use it

When you need to know which dropped items are currently visible and reachable
Before moving or pathing to collect loot to prioritize nearest or pickable items
To populate automation agents with precise item entity data for decision making
When auditing nearby item counts and types without scanning blocks
To detect missing items or verify that expected drops are present

Best practices

Keep radius at or below 7 (default) because the tool enforces a 7-block maximum
Retry observation if conf is 'low' to improve completeness or move closer and re-run
Combine with block-scanning tools when you need chest or container contents (this tool only reports entities)
Use the structured data.items.nearby for programmatic analysis and sorting by distance
Prefer short, frequent observations (conf='high') when many items are present to avoid slow scans

Example use cases

Scan a mob farm floor to collect and prioritize high-value drops (e.g., diamonds, enchanted gear)
Automate a collection bot by feeding it nearest-item coordinates and pickup affordances
Verify that a chest-emptying routine left no dropped items in a work area
Quickly list and count visible item types after large-scale block breaks or explosions
Filter and report only immediately pickable items for on-foot looting runs

FAQ

What radius can I use?

The tool defaults to 7 blocks and enforces a maximum of 7 blocks. Use the radius or entities_radius input up to 7.

What does conf mean?

conf indicates observation completeness: 'high' is complete and fast, 'med' may be complete but slow, and 'low' indicates an incomplete scan that may need retrying.