Skip to main content
Glama

bsp-mcp

by io.github.pscale-commons

pscale_grain_reach

Establish a grain at a federated beach — first durable bilateral commitment. Symmetric: same call from either side. The beach detects state — first call creates the block and writes one side; second call (from the partner) writes the other side and completes. Lex-smaller handle occupies side 1; lex-larger occupies side 2. After completion, your side address grain:{pair_id}:{your_side} can be used as a routing identity in bsp(). Defaults to https://beach.happyseaurchin.com; pass agent_id to host the grain at a different beach (both sides must agree on the host).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
handleYesYour bare-name handle. Used to compute pair_id and determine which side (1 or 2) you occupy.
agent_idNoURL of the beach hosting the grain. Defaults to https://beach.happyseaurchin.com. Both sides must use the same beach (the grain block has one home). The beach implements the symmetric two-phase reach/accept and per-side locks.
descriptionYesMutual description — becomes the root underscore. Used only on first reach; ignored on accept.
verify_onlyNoDry-run: when true, evaluate what this call WOULD do without writing or notifying. Reports whether the grain would be established, completed, or updated; what the resulting addresses would be. Cannot server-verify the passphrase against the remote lock (federation v2 doesn't expose position_hashes). No state mutation. Default false.
my_passphraseYesWrite-lock passphrase for your side. Hashed and stored at the beach. Sensitive — never repeat in conversation.
partner_handleYesTheir bare-name handle. Must be different from yours.
my_side_contentYesWhat you write at your side's underscore. Your synthesis or commitment statement.

TDQS

A4.5/5.0
Behavior5/5

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

Beyond the annotations, it discloses the two-phase creation/completion behavior, side assignment by lex order, resulting address format, default beach and agent_id behavior, and verify_only dry-run semantics with no state mutation. It also notes a limitation about passphrase server verification in federation v2.

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 description is a single dense paragraph, but every sentence contributes necessary protocol details. It front-loads the purpose and then explains process, side assignment, address result, and host configuration. Some bullet structuring could improve readability, but length is justified by the tool's complexity.

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?

The description thoroughly covers the protocol, side computation, address format, and verify_only semantics. It does not explicitly describe return values or error conditions, and there is no output schema, leaving a small gap. Overall, high completeness given the complexity.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining how handle/partner_handle determine sides, that description is only used on first reach, and the verify_only dry-run behavior, enriching parameter understanding beyond schema definitions.

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?

The description clearly states "Establish a grain at a federated beach — first durable bilateral commitment," providing a specific verb and resource. It distinguishes the tool by explaining the symmetric two-phase reach protocol, which differentiates it from sibling tools like pscale_invite.

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?

The description gives clear context: it is the first durable commitment in a two-phase process, symmetric from either side, and both sides must agree on the host. It lacks explicit alternative tool exclusions, but the usage context is strong.

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

All bsp-mcp toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4/5.0
Disambiguation4/5

Each tool targets a distinct primitive of the beach substrate: block I/O, floor alignment, pools, streams, settlements, identity, SAND, verification, world entry, and agent wakes. The descriptions explicitly separate near-neighbors like pool vs stream and networking vs verify_rider, though a few pairs (bsp/bsp-floor, play/invite) could still be confused on name alone.

Naming Consistency3/5

The pscale_ prefix provides a consistent family marker, but the verb/object pattern is mixed: bare verbs (invite, play, settle), object-verb compounds (key_publish, pool_engage, stream_engage), a verb-object compound (verify_rider), and nouns (genus, networking). bsp and bsp-floor also break the snake_case convention, keeping the naming readable but not strongly predictable.

Tool Count5/5

Twelve tools is well within the well-scoped range for a server of this breadth, and each tool maps to a distinct capability: core bsp, floor alignment, identity, grains, pools, streams, collectives, worlds, SAND networking, verification, and agent wakes. No tool feels redundant given the described domain.

Completeness4/5

The surface covers the main lifecycle areas: block read/write/discovery, key publication, bilateral grains, pools, streams, settlements, world entry, SAND networking, and rider verification. Minor gaps exist—passport creation is a prerequisite for key_publish but is only implied as a bsp write, and instance/world creation is referenced rather than directly exposed—so agents may need to work around a few edges.

Resources