Skip to main content
Glama

entity_state

state(entity, as_of) — ONE packet for one entity at a date (YYYY-MM-DD, default today): target (the entity as WE held it at as_of — before record time began, as held now, labelled), pins (look_from's frame, only pins we held by as_of; later additions counted), graph (its 1-hop relationships VALID at as_of — began on/before as_of, or stated by a source on/before as_of with the start unknown, and not ended by as_of — each with why; excluded edges counted by reason; never today's edges painted onto a past date), image (look_at's still for as_of — as_of is the SCENE's date, within 10 days — or untestable: true with the nearest scene's date), and escrow_oracle (available: false: no trade or oracle claim carries a site reference — said, not faked). AGENT KEYS ONLY (a browser session is refused BEFORE any charge). SIDE EFFECTS: none beyond the charge — read-only. ⚠ CHARGING: ONE quote, ONE debit = the live prices of the three parts (pins at the basic class + one graph hop + look_at's price), reserved up front and settled for the parts DELIVERED — a part with nothing in it (no pins, no edge valid at as_of, an UNTESTABLE image) is not charged; nothing delivered costs nothing. Quote with billing_quote("/api/v1/entity.state"); the JSON carries charged_joules and a price block (parts_base_joules, parts_delivered).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idYes
as_ofNo
max_cloudNo
radius_kmNo
entity_typeYes

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

B3.4/5.0
Behavior4/5

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

The description discloses significant behavior beyond what would be expected from the schema: charging model (one quote, one debit, reserved up front, settled for parts delivered), agent-key requirement, side-effect profile (read-only), and the escrow_oracle behavior. No annotations are provided, so the description carries the full burden, and it does so reasonably well. Some details (e.g., the exact interaction with billing_quote) are present.

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

Conciseness3/5

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

The description is long and dense, with many parenthetical asides and specialized jargon. It is front-loaded with the core operation, but the charging section and extensive behavioral details make it hard to scan. Every sentence does carry information, but the structure could be clearer.

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?

Given the tool's complexity (composite outputs, charging model) and the presence of an output schema, the description provides substantial context: output fields, charging behavior, key requirements, and read-only nature. The lack of parameter explanations for 3 of 5 parameters is a notable gap, but overall it is fairly complete.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate for the 5 parameters. It mentions `entity` and `as_of` implicitly but does not explain `max_cloud`, `radius_km`, or `entity_type`. Even `as_of` format is given (YYYY-MM-DD, default today), but other parameters are left entirely undocumented, which is a significant gap.

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?

The description opens with 'state(entity, as_of) — ONE packet for one entity at a date', stating a clear verb-like operation and scope. It names the composite outputs (`target`, `pins`, `graph`, `image`, `escrow_oracle`), which differentiates it from sibling tools like `entity_history` and `relationships`. However, the terminology is highly specialized and doesn't explicitly contrast with sibling tools.

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

Usage Guidelines3/5

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

Usage context is implied (query entity state at a date), but there is no explicit 'when to use this vs entity_history or relationships' guidance. The charging warning and key requirement are functional conditions, not alternative-selection criteria.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources