Skip to main content
Glama
LinkedParticles

Particles

Official
by LinkedParticles
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

subjects_show

Retrieve a subject by UUID, prefix, name, or alias and return its linked particle IDs, capped for token limits, plus the true particle count.

Instructions

Show one subject with the particle IDs linked to it.

Args:
    subject_id: A full UUID, an unambiguous prefix (≥ 8 chars), or a
        name or alias, matched case-insensitively and exactly. A
        reference that matches more than one subject (a prefix shared
        by several IDs, a name two subjects share, or a string that is
        both a prefix and a name) raises with the candidates named. A
        remote engine resolves IDs and prefixes only.
    particle_id_limit: Maximum particle IDs to include in
        ``particle_ids`` (default 100). For hot subjects the full
        list can blow the per-tool-result token cap; use
        ``particles_list(subject_id=…, limit=…, offset=…)`` for
        the full set when ``particle_count > particle_id_limit``.

Returns:
    Dict with ``subject`` (Pydantic JSON), ``particle_ids`` (capped
    at ``particle_id_limit``, ordered by id for stable pagination),
    and ``particle_count`` — the true total of linked particles,
    so callers can detect when the list was truncated.

Input Schema

NameRequiredDescriptionDefault
subject_idYes
particle_id_limitNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.210.2

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: ambiguity raises an error naming candidate subjects, remote engines restrict resolution to IDs and prefixes, results are capped and ordered by id for stable pagination, and particle_count reveals truncation against the token cap. These are non-obvious failure modes and limits an agent could not infer elsewhere.

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?

The opening sentence front-loads the core behavior, and the Args/Returns blocks are dense with genuinely useful detail. The RST-style code markup and docstring formatting add a little visual noise, but no sentence is redundant.

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

Completeness5/5

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

For a two-parameter lookup with no annotations, the description covers resolution rules, error behavior, truncation detection, and pagination escape hatch. Although an output schema exists, the Returns block still clarifies the meaning of particle_count and the ordering of particle_ids, which the schema alone would not convey.

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

Parameters5/5

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

Schema coverage is 0%, so the description must compensate and it does fully: subject_id accepts a full UUID, an unambiguous prefix of at least 8 characters, or a name/alias, matched case-insensitively and exactly, with the ambiguity conditions spelled out. particle_id_limit is explained as a cap with a stated default of 100 and the reason for its existence.

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 ('Show one subject') plus the associated payload ('particle IDs linked to it'). The singular 'one subject' implicitly separates it from siblings subjects_list and subjects_search, so an agent can select it without reading either schema.

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?

Explicitly routes the agent to particles_list(subject_id=…, limit=…, offset=…) when the linked list is truncated, which is a concrete alternative with a triggering condition. It also warns that a remote engine resolves IDs and prefixes only, which governs how the tool can be called. It never says when to prefer subjects_search to resolve an unknown reference, so it falls just short of full when/when-not coverage.

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

Deploy Server

Other Tools