openglass-mcp

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

With no annotations, the description carries the transparency burden and largely meets it: it discloses that prepare returns the offer and offerHash, that submit sends a signed Accept and 'activates the session', and that auth is a signed GET vs signed POST depending on mode. It does not detail failure behavior or what the submit response contains, but the main side effects and sequencing are clear.

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 front-loads the tool's role before explaining the two modes. The final verify_agent sentence is useful guidance rather than fluff, though the long mid-sentence parenthetical makes it slightly harder to scan.

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 6-parameter tool with nested objects, no output schema, and no annotations, the description covers the essential decision sequence: inspect with prepare, sign the correct object, submit with a signed POST, and optionally verify the counterparty first. It could be more explicit about the inviteId source and submit response, but an agent has enough to proceed correctly.

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 only 50%, but the description adds real meaning beyond the schema: it explains mode=prepare vs mode=submit, when token is required for open invites, how auth differs between modes, and that offerHash should be signed. Some parameters like inviteId are still only inferred from the tool name, but the core execution flow is clarified.

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 by naming the resource ('accept an invite') and explicitly positions it as 'the other half of start_session/invite_counterparty', differentiating it from sibling tools. It distinguishes direct vs open invites and names the two modes, so an agent knows exactly what this 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?

It gives clear context: use prepare to inspect the offer/hash before building the Accept, then submit to activate the session. It also recommends verify_agent as a pre-acceptance validation step with the initiator's agentId, though it does not explicitly state when to avoid this tool in favor of sibling tools.

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 no annotations, the description carries the burden and discloses the key behaviors: prepare uses a signed GET and returns the head, submit uses a signed POST and submits the statement, and closing starts record issuance. It does not cover reversibility, error conditions, or rate limits, but it conveys the critical side effects and mode distinction.

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?

Two dense sentences contain the action, endpoint, side effect, and both mode workflows; there is no filler. The verb/resource is front-loaded, and every clause earns its place.

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 five-parameter tool with nested objects, no output schema, and no annotations, the definition is not fully self-contained: it relies on SPEC §7.4/§12 for statement/signature construction and does not describe submit responses or errors. Still, the mode workflow and endpoint give an agent enough to make a reasonable first call.

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 only 40%, and the description adds useful meaning by mapping mode to HTTP verb/behavior and describing auth as a signed GET/POST. However, it does not clarify the relationship between auth, signature, and statement, nor how the prepare output feeds headSeq/headHash, leaving important parameter semantics to the external SPEC.

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 verb and resource — 'Close your own active attestation' — and identifies the exact endpoint. It names the side effect (starts record issuance) and mentions close_session, but it does not explicitly contrast close_attestation with its close_session sibling, so it falls just short of full differentiation.

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 gives clear operational context: only your own active attestation, and it spells out the two-mode workflow (prepare returns the current head; submit sends the signed CloseStatement). It does not state when to prefer close_attestation over close_session or list exclusions, but the resource scoping makes the primary use case clear.

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 no annotations, the description carries the full burden. It discloses important side effects: the platform builds an evidence bundle, signs a record, and both owners can retrieve it. It also explains auth requirements for each mode. It does not cover irreversibility or error cases, but the main behavioral impact is transparent.

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 two sentences with no filler. It front-loads the purpose and outcome, then efficiently explains the mode-specific flow. Every sentence earns its place.

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?

This is a complex tool with nested objects, no output schema, and no annotations. The description explains the overall flow and modes but omits response format, error conditions, and relies on an external SPEC for constructing the CloseStatement. It is adequate but leaves notable gaps.

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 only 40%, so the description must compensate. It adds meaning for mode (prepare/submit), auth (signed GET vs POST), and statement (built per SPEC §7.4). However, it does not clarify sessionId or the signature object beyond what the schema already provides.

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 closes an active session and starts record issuance, with a specific verb and resource. It does not explicitly differentiate from sibling tools like close_attestation or pause_session, so it misses the top score.

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 operational context by explaining the two modes: prepare returns the current head, and submit sends a signed CloseStatement. It does not explicitly state when to use this tool versus alternatives, but the mode-specific guidance 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?

With no annotations, the description carries the burden and does well: it discloses the access-control restriction, the closed-session requirement, and the two output modes (signed record summary vs. full downloadable bundle). It does not describe error behavior for unauthorized or unclosed sessions, but the core behavioral contract is transparent.

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?

Two sentences with no filler; the key action and constraint are front-loaded, and the recordId fallback is a separate, well-placed clarification. It is slightly dense with nested references, but every clause adds value.

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 single-purpose read tool with no output schema, the description covers what is returned, when it is available, who may call it, and how to get the required ID if missing. Missing details like explicit error codes are minor; the description is complete enough for correct invocation.

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 only 33% because recordId has no schema description, so the description adds crucial meaning by explaining how to obtain recordId and that it must belong to a closed session. It also clarifies the bundle parameter as 'full downloadable verification bundle' vs. the summary. The auth parameter is left to the schema, which already documents it thoroughly.

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 states a specific action and resource: 'Fetch the signed record for a closed session,' and even names the HTTP endpoint and the optional bundle mode. This makes the tool's purpose unmistakable and clearly distinct from siblings like send_message or verify_agent.

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 explains the only precondition (session must be closed) and provides a fallback path when recordId is missing: read it off the session via send_message's prepare mode. It does not explicitly list exclusion conditions, but the closed-session constraint and the access restriction ('only the two participant agents and their owners') give clear usage 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?

With no annotations, the description carries the behavioral burden well: it discloses a pre-flight GET /v1/agents/{id} existence/active check whose purpose is to return a clear error rather than a dead session, and it warns that signing must be done by the caller. It does not cover response shape, idempotency of re-inviting, or failure modes beyond the pre-flight check, so it falls short of full disclosure.

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 dense sentences, front-loaded with purpose and the pre-flight rationale, then the requirement and signing constraint. Every sentence adds information; slightly dense but no waste.

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 nested, cryptographically signed mutation tool with no output schema and 25% schema coverage, the description covers the key requirement and one behavioral trait but omits error-handling details, response expectations, and most parameter semantics. Adequate but with clear gaps.

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 only 25% on a 4-parameter nested schema, so the description must compensate. It does add real meaning for offer.counterparty (must be set, not null) and the signing requirement, but it says nothing about the visibility parameter or the offer fields (mode, timeouts, expiry), leaving most of the low-coverage surface undocumented.

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?

States a specific verb (invite) and resource (a known counterparty), and explicitly frames itself as a convenience wrapper around start_session for the case where the counterparty id is already known. The sibling it is distinct from (start_session / open invite) is named directly, so an agent can route without opening either schema.

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?

Gives explicit when-to-use ('you already know the other agent's id') and the when-not with the named alternative ('not an open invite — use start_session for that'). This is precisely the routing guidance the sibling set demands.

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 no annotations, the description carries the full burden and does so: it declares no signing, no auth, and free; explains that activity numbers are 'conservative by design, not a popularity score'; lists the flag types returned; and explicitly refuses prescriptive advice ('never tells you to block or refuse anyone'). This is unusually rich behavioral context for a read tool.

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?

Front-loads the action and the routing condition, then layers return detail. Sentences mostly earn their place, but the 'SPEC §14' citation and the long parenthetical on counting methodology add length without helping an agent decide or invoke.

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?

No output schema exists, and the description compensates by describing both the registered and unregistered return shapes in prose. It is nearly complete for a 4-param read tool, though it omits failure behavior (invalid input, no signal found at all) and per-parameter format guidance.

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 0% and the schema has no required fields or oneOf constraint, so the description's 'pass exactly one of agentId, domain, agentCardUrl, or publicKey' supplies the critical mutual-exclusivity rule and names all four parameters. It does not explain the expected format of each input (e.g., key encoding or URL form), which keeps it at a 4.

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?

States a specific verb+resource ('look up a counterparty') and its scope, plus what the return contains for both registered and unregistered agents. The framing 'BEFORE accepting an invite or offering a session' separates it from siblings like verify_agent and invite_counterparty without needing the schema.

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?

Explicitly says when to call it (before accepting an invite or offering a session) and how to pass inputs ('exactly one of...'). It also sets interpretation boundaries ('informational — decide for yourself'). It does not name a sibling alternative or state when not to use it, 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?

With no annotations, the description carries the full burden and discloses key traits: it is relay-only, requires you to build and sign the open yourself, activates immediately with no invite/accept, mandates that open.attestor be your own agentId/kid, and notes the record can later be fetched/verified. It does not cover error behavior or idempotency, but the core behavioral context is strong.

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 with the core purpose front-loaded. Each sentence adds distinct information (definition, signing/relay, contrast with start_session, attestor constraint, post-close verification), though the density is high and could be slightly more scannable.

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 annotations, output schema, and low parameter description coverage, the description provides a solid high-level picture: what the tool does, how to prepare the payload, activation semantics, and follow-up verification. It still omits some nested parameter details, but covers enough for an agent to invoke the tool correctly in most cases.

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 only 20%, so the description must compensate heavily. It adds a critical constraint for open.attestor and the purpose value, but leaves auth signing mechanics, openSignature, visibility, and idleTimeoutSec largely unexplained beyond what sparse schema text provides. Partial compensation is present but insufficient for this complexity.

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 states a specific verb and resource: logging a one-party attestation that the tool only relays. It explicitly distinguishes this from start_session and names related tools (get_record, verify_agent), so an agent can identify its role without opening the schema.

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 says to use this for logging something your agent itself did with no counterparty, and contrasts with start_session (no invite/accept, activates immediately). This gives a clear context, though it does not explicitly enumerate when to choose this over other attestation-related siblings like send_attestation_event.

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 no annotations, the description carries the full burden. It discloses that the action blocks further send_message calls, that it's irreversible from the caller's side, and that the owner must act from the dashboard. This is solid, though it could mention what happens on decline (e.g., session state) for completeness.

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?

Two sentences with no fluff, front-loaded with the action and examples. The structure is efficient and readable, though slightly dense. It earns a 4 for being appropriately concise without sacrificing key details.

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 no annotations, the description covers purpose, usage, and main behavioral effects. It doesn't detail error handling beyond session_not_active or the exact resume/decline flow, but these are secondary. For a pause action, it's sufficiently complete for an agent to call it correctly.

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 only 33% (sessionId has no description, and auth is nested with its own descriptions). The description adds minimal parameter meaning—only implying sessionId is your own session. It does not clarify the auth parameter's role beyond what the schema already provides, failing to compensate for the low 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 clearly states the action (pause a session), the specific resource (your own active session), and distinguishes it from alternatives ('rather than sending the next message or closing outright'). Concrete examples (price, legal term) further clarify intent, making it unambiguous.

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 explicitly contrasts with sending a message or closing, and provides contextual triggers (before agreeing to something needing human review). It also explains the consequence (blocks send_message) and the owner's role in resuming/declining, giving clear when-to-use guidance.

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 no annotations, the description carries the full transparency burden and does so thoroughly: it discloses that the server verifies the signature against the submitted publicKey, that the response includes a claim URL, that no session can start until claimed, and that start_session returns agent_unclaimed until then.

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 but front-loaded with the core purpose, and every clause adds useful information for a complex authentication flow. It could be slightly more scannable with structured bullets, but it is appropriately sized for 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?

For a tool with nested auth parameters and no output schema, the description covers the request flow, response hint (claim URL), and post-registration behavior well. Minor gaps remain around where the agentId comes from and the full response shape, but the essential calling sequence is complete.

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 60%, and the description adds critical meaning beyond the schema, especially around auth: the literal 'new' value for kid, the signature computation, and the publicKey ownership proof. It does not discuss meta or the name/description fields, but those are already described 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 first sentence states a specific action and resource: 'Register yourself as a new OpenGlass agent.' It also clarifies that this is a one-time setup step preceding witnessed sessions, which distinguishes it from the session-operation siblings like start_session and send_message.

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 'Use this once, the first time...' and lays out concrete preconditions: generate a keypair, sign the request, and set auth.kid to 'new'. It also routes follow-up behavior to verify_agent or start_session, giving clear alternative choices.

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 no annotations, the description carries the full burden and does so well: it discloses the request-signing format (sign the body as `{ <that one field> }`), the privacy behavior (OpenGlass fetches the card itself and stores only its URL and hash, never the submitted content), the auth requirement (claimed agent), and the error contract (409 already_registered with details.agentId). These are non-obvious operational traits an agent genuinely needs.

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?

Dense but every clause earns its place: trigger, method, one-of constraint, privacy note, auth prerequisite, and error. The SPEC citation leads rather than the action, and the single block-sentence form is slightly heavy, but nothing is redundant.

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?

Covers the trigger, exclusivity constraint, signing, prerequisite, and failure mode for a mutation-style call with no annotations and no output schema. The only gap is the success response shape, though the 409 mention partly implies the contract and is a minor omission for a listing 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?

Schema coverage is 0% and the schema gives no descriptions for domain/agentCard/agentCardUrl, so the description must compensate—and it does. It states you must pass exactly one of the three fields, explains that agentCard is the A2A card as received, and clarifies the body-signing shape around that single field.

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?

States a specific verb and resource—listing an unregistered agent as an 'unclaimed profile'—and immediately scopes it to the case where lookup_agent returned registered: false. An agent can distinguish this from siblings like register_agent, invite_counterparty, and lookup_agent without opening any schema.

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?

Gives a clear trigger ('when the agent you're dealing with isn't registered... lookup_agent returned registered: false') and names the prerequisite that the caller must be a claimed agent. It does not, however, point to the alternative for the opposite case (an agent that IS registered, e.g. invite_counterparty), so the when-not side is only implicitly covered by the 409 already_registered note.

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 no annotations provided, the description carries the full burden, and it delivers: it discloses that the tool is a relay ('this tool only relays them'), that it never computes signatures or holds private keys, that prepare returns the current head, and that the sender is always the user's own attestor key. This significantly reduces the risk of an agent assuming the server will build the envelope or verify counterparties. It stops short of describing side effects, failure modes, or what submit returns.

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?

Three sentences, each earning its place: the first defines the operation and sibling relationship, the second maps the two modes end-to-end, the third removes ambiguity about relaying and key ownership. It is dense rather than fluffy, though the SPEC references assume domain familiarity.

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 7-parameter tool with nested objects, no output schema, and no annotations, the description covers the two-mode control flow, auth requirements, and relay behavior well. However, it never explains where attestationId comes from (e.g., open_attestation), what a successful submit returns, or any precondition beyond 'active attestation.' These are material gaps for an agent deciding how to invoke the 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?

Schema coverage is 57%, so the description meaningfully supplements the schema. It explains the mode enum by tying prepare to a signed GET and submit to a signed POST, clarifies which parameters belong to submit (envelope/hash/signature/payload), and draws the critical distinction between the request 'auth' and the event 'signature.' It also flags the notary-mode payload constraint that the schema describes only loosely.

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 verb and resource: 'Append a signed, hash-chained event to your own active attestation' plus the exact HTTP path (POST /v1/attestations/{id}/events). It explicitly positions this as 'the one-party counterpart to send_message,' which differentiates it from its closest sibling without needing to open the schema.

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 names send_message as the alternative and defines the condition that selects this tool: one-party operation on 'your own active attestation' with 'no counterparty to pin against.' It also explains when each mode is appropriate (prepare to discover the current head, submit to append). It does not explicitly enumerate when-not-to-use cases, but the counterparty framing makes them clear.

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 no annotations, the description carries the full behavioral burden. It discloses that the tool only relays client-built envelopes, that stale seq/prevHash values are rejected with chain_conflict, and that the client must construct the envelope, hash, and signature per SPEC §7.3. It could add return-value details, but the core mutation and failure behavior are transparent.

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: it states the action, then the two modes with their auth requirements, then a clear directive to build signed artifacts client-side. Every sentence earns its place, and the most important guidance 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?

The description covers the main workflow well, but with no output schema it does not explain what prepare or submit return, which an agent needs to know to proceed. It also omits the notary-mode distinction that appears in the schema, where payload must be omitted, leaving a meaningful gap 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?

Schema coverage is 57%, so the description adds needed context. It explains the meaning of mode values, maps prepare to a signed GET and submit to a signed POST, and clarifies that envelope/hash/signature/payload are required only for submit. This goes beyond the schema by describing the operational relationship between 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 opens with a specific verb and resource: 'Append a signed, hash-chained message to an active session', and names the exact endpoint. It clearly defines two modes, prepare and submit, which distinguishes this tool's behavior from the sibling tools that manage sessions or attestations.

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 operational guidance: 'always do this first unless you're already certain of the head' for prepare mode, and explains when submit is appropriate. It does not compare against sibling tools, but the two-mode workflow and the chain_conflict caveat provide clear context for when and how to use this tool.

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 no annotations, the description carries the burden and does well: it discloses that the tool only relays a pre-built offer, that you must sign it yourself, and that invite_counterparty adds a pre-flight existence check this tool lacks. It stops short of describing the success response or what the open bearer invite exposes, so it is not fully complete.

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, front-loaded with the action and prerequisite, then the routing alternative. Dense but each clause adds decision-relevant information; only the trailing 'into the void' phrasing is decorative.

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?

Covers the key decision points (prerequisite, invite mode, sibling alternative) for a tool with nested objects and no output schema. Missing mode semantics and return/response expectations, but what an agent needs to choose and construct the call is largely present.

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 low (25%), so the description must compensate, and it meaningfully explains offer.counterparty (direct invite vs null open invite) and the offer's purpose field. However, mode (relay/notary), idleTimeoutSec, the auth signing block, and how sessionId relates to the offer are left to the schema, leaving significant gaps for such a complex nested payload.

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?

States a specific verb and resource ('Offer a witnessed session to another agent') plus the underlying endpoint (POST /v1/sessions), and explicitly contrasts itself with the sibling invite_counterparty. An agent can distinguish it from the other session tools without opening the schema.

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?

Gives explicit prerequisites ('You must be claimed already (see register_agent)'), the branch condition for counterparty (known agentId = direct invite, null = open bearer invite), and a routing rule ('prefer invite_counterparty instead' when the agentId is known, with the reason). This is a full when/when-not/alternative set.

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 no annotations, the description carries the burden well: it discloses that the bundle path is a public check requiring no signing, and that both paths avoid trusting OpenGlass's own word. It does not state what happens on verification failure (rejection vs. error result), which is the main remaining gap.

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?

Front-loaded with 'Two independent checks, pick one', then each branch is a single dense sentence. Slightly long but every clause carries routing or behavioral information; no filler.

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 heavily nested input, no output schema, and no annotations, the description covers input modes and trust semantics well but says nothing about the return value (e.g. what a verification result contains or looks like on failure). Given the absence of an output schema, some statement of return shape would help.

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 0%, but the description compensates by explaining what each of the two parameters means: agentId is a counterparty's public profile lookup, and bundle is 'a full record bundle, e.g. from get_record with bundle=true'. It points to the producing sibling, which is valuable, though it doesn't enumerate the bundle's internal structure (the schema does).

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 names two specific modes (agentId lookup vs. bundle re-verification) with distinct outcomes: confirming registration/claim status, and re-running full cryptographic verification against platform keys. An agent can distinguish this from siblings like lookup_agent and get_record without opening the schema.

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?

Explicit when-to-use for each mode: agentId 'before accepting an invite from someone you don't already know', and bundle when a court or auditor needs to verify without trusting OpenGlass. The two paths and their triggering conditions are unambiguous.

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