bsp-mcp

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

The description adds substantial behavioral context beyond the annotations (openWorldHint, idempotentHint, destructiveHint). It reveals that reads are 'a decision, not a default', warns against pulling 'a grown accumulator whole' because it 'drowns the context', and details lock semantics ('secret = proof of current authority; new_lock = target lock value'). It also exposes discovery behavior (listing block indices) and encryption nuances (gray default on grain blocks). This goes well beyond the minimal annotation hints, fulfilling the transparency requirement thoroughly.

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

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

The description is long and dense, but given the 13 parameters and high conceptual complexity, the length is justified. It is structurally organized: a one-sentence executive summary at the top, then DISCOVERY, READ-SHAPE, lock semantics, and parameter-specific notes. It front-loads the core behavior and later dives into details. However, some sentences are extremely compact and could be simplified, especially the parameter descriptions (e.g., append and members) which mix behaviors and use cases. Overall, it is efficient for the complexity, earning a 4 rather than 5.

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

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

The description is remarkably complete given the tool's complexity. It covers all three primary modes, includes discovery and index listing, details lock rotation and relinquishment (four cases), explains encryption (gray, members, enc_secret), and provides examples for append and grain sides. It even gives a recommended first call and references internal teaching branches. Without an output schema, the description still explains what the read returns (e.g., the derived index) and the ack for appends. Every operational aspect is addressed, making it contextually complete for a newcomer and an expert.

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

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

Although schema description coverage is 100%, the tool description enriches parameter understanding significantly. It explains the interaction between spindle and pscale_attention ('Together with spindle, derives the selection shape') and details the shape vocabulary (point, path-walk, disc, block). It clarifies the distinction between secret and new_lock (editorial latch vs. encryption key), and conditions for append (growth, supernesting). The description adds semantic layers beyond individual parameter definitions, e.g., the DISCOVERY mode when block is omitted, and the fallback behavior of enc_secret. This is far above the baseline 3 for high coverage.

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

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

The description opens with 'The unified bsp() function' and immediately delineates the three modes: 'Read when content + new_lock both omitted; write when content provided; set/rotate lock when new_lock provided.' It names the two coordinates (spindle, pscale_attention) and states their roles. This is a specific verb+resource declaration that distinguishes bsp as the primary unified interface, clearly separating it from sibling tools (e.g., bsp-floor, pscale_key_publish) by covering read/write/lock in one function.

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

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

The description provides explicit usage rules: 'Read when content + new_lock both omitted; write when content provided; set/rotate lock when new_lock provided.' It also prescribes a recommended entry point: 'Recommended first call: bsp(agent_id="pscale", block="whetstone")' and gives discovery guidance ('omit block (or pass "") to LIST a surface'). It explains when to use the read-shape probe ('probe an unknown or grown block with the disc at pscale 0 first') and directs to internal references (pscale://whetstone branches). While it doesn't explicitly name alternatives, it establishes the tool's role as the main entry and gives clear context for choosing modes.

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

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

Beyond the readOnlyHint annotation, the description reveals a fundamental behavioral rule: 'cross-block correspondence is by pscale, NEVER by walk depth', plus the padding behavior and pscale 0 semantics. This adds significant context about how the tool behaves, exceeding what the annotations already convey.

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

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

The description is dense and multi-sentence, but each sentence carries substantive content: the core operation, the cross-block correspondence law, the floor-plane meaning, and user modes. While not as terse as possible, the complexity of the tool justifies the length.

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

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

Given no output schema and only readOnlyHint/openWorldHint, the description thoroughly covers the tool's geometry, alignment rules, padding behavior, pscale 0 semantics, and how to interpret the result. The external references further aid an agent's understanding. It is complete for a complex tool.

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

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

With 100% schema coverage, parameters are already well documented. The description adds extra meaning by explaining that pscale 0 serves as an index of root definitions and describing the n>2 alignment logic for the targets array. This enriches the schema but doesn't reach a 5 because the schema itself is already detailed.

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

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

The description clearly identifies the tool as 'The n-ary companion to bsp()' and states it 'Lays two or more blocks against the common floor plane and returns them aligned by pscale'. This is a specific verb, resource, and output, and it explicitly contrasts with the sibling bsp().

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

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

The description provides clear usage context by distinguishing the two-block case as a comparison versus n>2 as multi-block alignment, and gives explicit user modes ('compare, merge, or resonance'). However, it does not explicitly state when not to use this tool or name alternative siblings (beyond bsp()), so it stops short of a 5.

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

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

The description goes far beyond annotations, detailing the three modes, locking enforcement, fold application semantics, refusal reporting to conditions:9, and the fact that the tool holds no clock. It discloses destructive behavior (HOLDER writes) consistent with destructiveHint=true and adds context like history being refused as an automatic memory.

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

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

The description is front-loaded with the core purpose and logically structured (purpose, modes, fold contract, exclusions). However, it is lengthy and contains some metaphorical or rhetorical sentences ('koan and clouds riding in it', 'you are the pulse') that don't add operational value, making it slightly less concise than ideal.

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

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

Despite no output schema, the description specifies the response shape (SYSTEM and MESSAGE) and the byte-identical guarantee. It covers the fold contract, all modes, error pathways (refusals), and the recommendation to call again for the next window. Given the tool's complexity, this is a complete and self-sufficient description.

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

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

Schema coverage is 100%, but the description adds meaningful context: passphrase unlocks HOLDER mode, task is only accepted with the passphrase and is appended to the given, and fold obeys the capabilities:3 contract. This goes beyond the schema's field descriptions, though the schema is already detailed.

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

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

The description clearly states the tool's function: it returns the instance's COMPOSED context window, letting the caller wear the genus-one agent's mind for a wake. It distinguishes itself from sibling bsp() by explicitly warning against hand-assembling the window from bsp() reads.

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

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

Provides explicit guidance: use this tool to obtain the composed wake window, not bsp(); use passphrase for HOLDER mode to apply folds, or no passphrase for ghost-wake. It also explains when to engage from outside via bsp() (leave a mark, add to pool) for peer interaction.

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

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.

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.

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.

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.

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.

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.

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

The description goes well beyond the readOnlyHint annotation by explaining what a bare call returns (a 'Character-voiced director's note' with specific actions) and that it hands the agent MOVES rather than a script, even warning against verbatim relay. It also describes the step progression's output format, including 'a concrete action and a validation criterion,' giving full behavioral transparency.

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

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

The description is dense but well-structured: first sentence establishes primary purpose, second details the bare-call behavior, third explains the step parameter. Every sentence carries essential information, and the opening is front-loaded with 'The welcome — call this FIRST.' However, the extended metaphorical language (e.g., 'blodge', 'keyless act') adds some length and potential ambiguity, so it earns a 4 rather than 5.

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

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

With no output schema, the description compensates by describing the expected return for bare calls (director's note, MOVES) and for step calls (concrete action and validation criterion). Combined with the schema's step enumeration and the readOnlyHint annotation, the tool is fully contextualized for an agent. Minor gaps like error handling or invalid-step behavior prevent a 5.

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

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

The schema already provides 100% coverage of the 'step' parameter with a detailed description of each step's meaning and progression. The description adds the crucial audience distinction ('ONLY for the OTHER audience') and the overall build-ladder context, which enhances understanding beyond the schema. This extra context justifies moving above the baseline of 3.

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

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

The description opens with 'The welcome — call this FIRST when a person arrives or asks what this place is,' clearly stating the tool's core purpose as an orientation entry point. It also distinguishes itself from siblings by explicitly being first and by describing two distinct audiences (human arrival vs agent build ladder), making its function unique among the listed siblings.

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

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

It provides explicit when-to-use guidance: 'call this FIRST when a person arrives or asks what this place is.' For the step parameter, it clearly says 'Pass step=1..6 ONLY for the OTHER audience — an agent orienting itself to build substrate capacity,' which clarifies exactly when to use the non-bare invocation and differentiates from the welcome scenario.

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

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

Beyond the annotations (idempotent, destructive, openWorld), the description discloses that the private half is never stored, that the same secret+handle always produce the same keys, and that the beach defaults to a specific URL but can be overridden with agent_id. It also explains the rotation proof requirement, adding significant behavioral context.

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

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

Four sentences contain everything needed: key derivation, publication target, private key handling, determinism, prerequisite, rotation condition, and default/override behavior. No filler or redundancy; the most important information is front-loaded.

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

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

For a tool with 6 parameters and no output schema, the description covers prerequisites, rotation, default behavior, determinism, and security properties. It is sufficient for an agent to select and invoke the tool correctly, including edge cases like rotation and custom beach URLs.

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

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 cross-parameter semantics: it explains that secret+handle both seed derivation via Argon2id, that enc_secret falls back to secret, and that prior_secret/signature are rotation mechanisms. This clarifies relationships not fully explicit in the schema descriptions.

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

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

The description opens with a specific action: 'Derive an X25519+Ed25519 keypair... Publish the public half at passport position 9'. It clearly states the resource (federated passport block 'passport:<handle>') and the outcome, fully aligning with the tool name and title while remaining distinct from sibling tools.

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

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

The description provides clear prerequisites ('Passport block must exist at the beach first') and conditional guidance for rotation ('Rotation requires proof of prior key ownership'). It does not explicitly name alternative tools for when this tool should not be used, but the context and purpose are unambiguous.

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

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

With dectructiveHint=true and idempotentHint=false already in annotations, the description goes well beyond them: it specifies exactly what mutates (passport receipt, GAVE at your out-ledger, signed chain hop, grain-side replies), what is never sent to the beach (enc_secret), when auto mode will and will not act, and that balances move on read. This is strong transparency and no contradiction with the annotations.

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

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

The description is long and dense, with nested parentheticals and run-on clauses that make it harder to scan than it could be. Every sentence does earn its place, but the structure is not exemplary: the same level of content could be organized more cleanly by verb, mode, and params.

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

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

There is no output schema, so the description compensates by stating the return fold {verified, kept, replied, forwarded, dropped, hau} plus marker_new. It also covers verification paths, permission modes, when slots are ignored, signing secrets, and write effects, which is complete for a tool of this complexity.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real parameter-level meaning beyond the schema: credit_accept 0..offered IS the transfer, endorsing writes a GAVE at your out-ledger, execute decisions run regardless of permission, and hau's split semantics. It complements the schema rather than repeating it.

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

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

The opening states a concrete job: walk a committed channel for new rider-bearing probes since a marker, verify them deterministically, and then PERCEIVE or ACT. It names the resource types (grain, pool, acumulator) and the two main modes clearly, and it does not confuse itself with pscale_verify_rider. The heavy SAND jargon (social neuron, passport 6.2, position 9) slightly obscures the core message for a non-expert reader.

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

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

The description makes the invocation context clear: use this to drive the L3 relay loop, and choose ask mode to get verdicts/cand idate verbs or auto/execute mode to act. The layering note ('sits above sand-rider and l3-relay; walk those to author probes') gives some alternative guidance. It does not, however, explicitly enumerate sibling tools or state 'use tool X instead when...'.

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

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

Despite readOnlyHint/openWorldHint/idempotentHint already covering the safety profile, the description adds substantial behavioral context beyond the annotations: the world-resolution algorithm (worlds block, sub-beach convention, full URL), session effects ('PINS the world's URL', 'engages the room pool'), the conditional GATE path for new handles, the HERE NOW vs ABOUT cast split, and the directive-inlining behavior. This is exactly the kind of disclosure that helps an agent predict side effects and return content.

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

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

The description is organized into scannable segments (returning holder, new handle, RPG, worlds note) and is front-loaded with the core promise. But it is roughly 300 words of ornate prose with decorative filler ('THE DOOR — two arrivals, one call', 'no-fiddle entry', 'passport riding') that could be cut without losing information, and one sentence ('no world needed') is actively misleading next to the required parameter.

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

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

For a complex 4-parameter tool with no output schema, the description covers the major branches (keyed session, new handle via GATE, RPG invocation), the world resolution paths, context bundling, and post-return expectations (inlined directive, scene, cast split) — partially compensating for the absent output schema. It stops short of complete: error/edge cases (unknown handle, unresolvable world) and the precise return payload shape are not specified, but this is a strong effort for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3; the description largely restates the schema rather than extending it (world resolution, room as a 'gloss', secret authorizing submits). It does add a few nuggets — the shell:<handle>:3 manifest reference, legacy witnessed/knows block names, and explicit call-signature examples — but it also introduces confusion by saying 'no world needed' while world is a required parameter, which undermines the added value.

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

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

The description does state a specific action and resource — 'play inhabits a persistent handle — a character, a user, or an agent' and 'compiles your shell's manifest into ONE framed window' — and it explicitly differentiates from pscale_invite ('invite is the welcome passage for a newcomer; play inhabits a persistent handle'). However, the theatrical framing ('THE DOOR', 'passport riding', 'no-fiddle entry') forces an agent to decode heavy metaphor before the plain meaning emerges, so it falls short of a 5.

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

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

The description gives explicit selection guidance against the closest sibling: use pscale_invite for newcomers, pscale_play for persistent handles. It also covers the three entry scenarios (returning holder, new-to-world handle, RPG character) and the GATE/lobby path for unkeyed handles. It does not, however, give when-not guidance against other siblings that share behaviors (e.g., pool/stream engagement tools), and some guidance ('follow the inlined directive every turn') is post-call instruction rather than tool-selection context.

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

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

The description goes well beyond the annotations by disclosing that submit overwrites a per-author liquid slot, contribution is an atomic append, clear destroys the entire liquid buffer but never committed contributions, and there is no central resolver. It also explains caller-managed markers and the WINDOW MOVED race guard. No contradiction with the annotations is present; destructiveHint=true is consistent with the described overwrite and clear behavior.

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

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

The description is a dense multi-clause wall of text with parenthetical digressions, all-caps emphasis, and repeated explanations such as the 'shared spool everyone pulls' framing. While much of the content is relevant, it is not easily scannable and would benefit from bulleted modes and shorter sentences. The front-loaded opening is useful, but the overall structure is not appropriately concise for an agent-facing definition.

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

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

Given the tool's high complexity, the description is remarkably complete: it covers pool creation, staging, committing, reading, clearing, secret/lock authority, default beach URL, resolution guards, and returned artifacts like marker_new, the social mirror, and WINDOW MOVED. With no output schema present, it still gives the agent enough return-behavior context to invoke the tool safely.

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

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

Schema coverage is 100% and every parameter already has a rich description, so the baseline is 3. The description adds cross-parameter semantics beyond the schema: submit and contribution may be combined, purpose is the canonical pool-creation path that must not be done via bare bsp(), and marker_new must be stored and returned. This nudges it above baseline, though most per-parameter meaning still lives in the schema.

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

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

The description clearly identifies the tool as engaging a pool with a synthesis envelope, and it specifies the two write modes (submit vs contribution) and read behavior over the since_position marker. It is specific about the spool primitive and warns against raw bsp(), but it never explicitly contrasts this tool with sibling tools like pscale_stream_engage or pscale_play, so sibling differentiation is incomplete.

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

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

The description gives explicit when-to-use guidance: submit for staging to the liquid buffer, contribution for committing, clear 'whenever someone asks for the pool, the room or the liquid to be cleared', and omit contribution for read-only engagement. It also explicitly routes RPG subjective resolution to the resolver's bsp() job and warns 'NEVER use raw bsp() with content=\'<purpose>\'', which tells the agent what not to do.

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

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

Annotations already declare openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds useful context about passphrase locking, hashing, and the 'not an account' clarification, but it does not disclose potential side effects, failure modes, or what happens to the world state beyond settling. This is above the bare minimum but not rich.

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

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

The description is informative and every sentence adds value, but the extended metaphor ('sediment layer settling into rock') makes it more verbose than necessary. The key facts are present but could be stated more directly.

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

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

The tool has no output schema, yet the description does not mention what the tool returns (e.g., the assigned position, confirmation, or errors). It explains the domain well but omits return behavior and edge cases, leaving the agent uncertain about the result of the operation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description additionally clarifies that the passphrase is later used as `secret` in bsp() and that agent_id selects the beach, but these are minor augmentations to already well-documented parameters.

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

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

The description clearly identifies the action ('Settle into a sedimentary collective') and the resource (a public group on a federated beach), and distinguishes this from account creation and edit operations via bsp(). However, the poetic metaphor obscures the direct statement of what the tool does, and it does not explicitly contrast with all 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.

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

The description implies when to use this tool (initial joining, not editing) by noting 'later edits via bsp()' and clarifying 'This is NOT an account or a sign-up.' It does not explicitly provide a when-to-use versus alternatives statement, nor does it mention any prerequisites or exclusions beyond the bsp contrast.

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

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

With annotations already declaring openWorld, idempotent, and destructive hints, the description adds substantial side-effect context: say 'lands in YOUR OWN mirror' and 'saying again at the same address replaces what you said'; keep writes to tree:<field>:<handle> or the bare <field> fold; 'A STREAM STORES NOTHING'; folds are 'ephemeral by default'; reads 'deliver THE LADDER'. It also explains what is never done: 'the primitive never synthesises'. No contradiction with the annotations.

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

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

The description is front-loaded with a purpose statement, but it is an enormous wall of text with heavy all-caps jargon, repeated concepts ('A PERSON'S DAY IS field="now"' and later 'THE INSTANCE EVERY HANDLE HAS IS field="now"' say essentially the same thing), and nearly no paragraph breaks. It contains valuable details, but not every sentence earns its place; it could be substantially tightened without losing meaning.

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

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

For a complex 9-parameter tool with no output schema, the description is remarkably complete. It explains every parameter, side-effect location, return behavior ('Reads deliver THE LADDER', 'omit at entirely to receive the spine's map'), the distinction from pool_engage, and the security rule around secret ('Sensitive — never repeat it in conversation'). Nothing needed to invoke the tool correctly is left undocumented.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes far beyond the schema definitions. It maps field values to intent ('A PERSON'S DAY IS field='now''), explains at as a named rung computed from the clock, specifies exactly where say and keep write, describes tier's read-only call semantics, and clarifies keep_text as 'Yours to write: this primitive assembles the snapshot and delivers the law, and never synthesises anything itself'. Every parameter gains real meaning beyond its JSON description.

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

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

The opening line clearly states the resource and action: 'WHAT PEOPLE ARE DOING, AND THE SYNTHESIS OF IT', and the description names the sibling it is not ('Distinct from pscale_pool_engage'). It is genuinely focused on stream/now-family reads and folds. However, the purpose is buried under dense invented vocabulary like 'V-L-S envelope' and 'spine-mirror-tree family'; a plain 'this tool reads and synthesizes current human activity on a stream' is never stated, so it is not a 5.

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

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

The description explicitly says when to reach for it: 'reach for this whenever someone asks what is happening today, what people are up to, how someone’s day or week is going, or asks for a summary or synthesis'. It also gives a when-not: 'Use another field ONLY when the person names a specific project or venture', and it names the alternative: 'Distinct from pscale_pool_engage, which owns a spool and a liquid buffer and serves windowed play'. This is explicit and actionable routing.

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

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

The description goes well beyond the readOnlyHint and openWorldHint annotations, explaining exactly how each dimension is evaluated, what verdicts mean, and edge cases like 'pass is never issued for a dimension that was not checked.' It also reveals fallback behavior and acceptance of both word-keyed and digit-keyed forms. This is richly transparent and lets an agent predict outcomes without having seen an invocation.

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

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

This is a long description, but the length is earned by the complexity of the four-dimensional verification. The description is front-loaded with a one-sentence summary, then uses a clear pattern for the four dimensions and closes with verdict semantics and usage constraints. It could be tightened slightly, but every sentence is informative and the structure aids parsing.

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

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

Given the absence of an output schema, the description supplies an explicit verdict enum and explains when each verdict is possible, including the caveat that a pass only occurs if the dimension was actually checked. It also covers input fallbacks, accepted forms, and uncertain cases like 'skipped if absent'. An agent has everything need to decide whether to call this tool and how to interpret its verdict.

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

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

Schema description coverage is 100%, so the parameters are already thoroughly documented. The tool description adds helpful high-level semantics — such as why chain, rider, probe_id, and topic_coordinate exist — and repeats the word/digit-keyed choice, but it does not materially extend what the input-schema descriptions already say. The schema carries the load here, matching the baseline expectation for a high-coverage definition.

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

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

The description opens with a specific directive — 'Deterministic arithmetic check on a SAND rider, v2' — making the operation and target unmistakable. It further breaks the check into four named dimensions (CHAIN, PROVENANCE, BALANCE, SQ) and lists possible verdicts, which fully conveys what the tool does.

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

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

The description's opening sentence and involvement in the sand-v2 context make it clear this tool is for verifying SAND riders; the field-level detail implies when it is appropriate to invoke it. It also states the tool is non-enforcing, so the agent knows it is for judgment rather than enforcement. It does not name explicit exclusions or alternatives, but the unique verify purpose is obvious among the siblings.

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