Behalf (PXP v0)

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 genuinely new behavior: the answer is sealed into the principal's card as an amendment, i.e. a durable record rather than a transient message, which is consistent with the non-idempotent hint. It also imposes a conduct constraint (relay verbatim, never substitute your own answer) that annotations cannot express.

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 short clauses, front-loaded with the trigger condition, then the effect, then the constraint. No filler, no repetition of schema content beyond what reinforces intent.

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 two-parameter, no-output-schema tool with annotations supplying the safety profile, the description covers trigger, action, persistence effect and the key prohibition. It does not say what happens after the answer is relayed (e.g. whether the room resumes), which is the only meaningful remaining gap.

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 both parameters (link, answer) are already fully documented, including the secrecy requirement on the link. The description's 'question verbatim' and 'their exact answer' reinforce the answer parameter but largely restate the schema's 'in their words'. Baseline 3 is appropriate when the schema does the heavy lifting.

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 a concrete verb (ask and relay) and a concrete resource (the principal's answer, sealed into their card), plus the trigger state ('when the room is paused for your principal'). An agent can tell this is the escalation-answer path rather than a generic message send, but no sibling (e.g. send_envelope, seal_intent_card) is named to sharpen the boundary.

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 'when' is explicit: the room is paused awaiting your principal. A clear prohibition ('Never answer on their behalf') functions as a when-not, which is stronger guidance than most tools give. It stops short of naming an alternative tool for the case where the room is not paused or no principal is present.

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?

Goes well beyond the annotations: it discloses the auth mechanism (principal's agent key as an Authorization: Bearer header, not an argument), where to obtain the key, that no passcode is required, and the precondition that counterpart_proxy='builtin' needs 'Use our AI' access. That is exactly the kind of setup information annotations like openWorldHint/destructiveHint cannot express.

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 the action and outcome, then packs in usage and auth prerequisites. Nothing is filler, but the final clause about counterpart_proxy is dense and the nested quotation is hard to parse on first read.

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 partially compensates by telling the agent what it receives (a private invite link). It covers auth, usage, and the enum caveat, but says nothing about failure modes or what the response body looks like for a non-idempotent creation.

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 adds genuine meaning: it clarifies the passcode's optional status ('No passcode is needed') and explains the counterpart_proxy enum's real precondition (builtin needs 'Use our AI' access, otherwise use external). The awkward inline quoting around "builtin" slightly muddies the reading.

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 ('Open a new room') and immediately explains the resulting structure: principal in seat A, agent gets a private invite link for seat B. An agent can tell this apart from join_room or get_room without opening either schema, since the description frames it as the no-room-yet path.

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 an explicit trigger ('Use this when your principal wants to negotiate with someone and has no room yet') and a behavioral constraint ('Send the invite only to that person'). What's missing is naming the sibling tools to use instead when a room already exists; the exclusion is implied rather than stated.

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 readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds the substantive behavioral fact that this artifact is only meaningful post-room and enumerates its sections, but says nothing about what happens if called mid-room or what errors/auth failures look like.

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?

A single tight sentence that front-loads the timing condition and the returned contents with no filler. It reads as a sentence fragment, which is efficient but leaves the action verb to the title.

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 usefully enumerates the brief's contents (agreed terms, authority, assumptions, escalations, ledger head), which is the right move. However, it leaves the room_id parameter, the link-vs-id selection, and pre-room behavior unexplained, so it is only adequate for a 2-parameter secure lookup.

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%: 'link' is documented as a secret seat link, but 'room_id' is undocumented in both schema and description. The description adds no parameter meaning at all and does not clarify whether link, room_id, or neither is needed despite zero required 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 resource is named precisely ('The decision brief') and the timing qualifier 'once the room has ended' distinguishes it from the live-state siblings get_room and wait_for_turn. It stops short of a verb (the title supplies 'Read'), so it is clear but not fully self-contained.

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?

'Once the room has ended' is an implied precondition that tells the agent when this tool is valid, but no alternative is named for when the room is still open, and no guidance is given for a room that never ended or a failed lookup.

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 readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe, external read. The description adds that the snapshot is seat-scoped and that it surfaces items needing review plus unverified assumptions, which is useful beyond the annotations, but it says nothing about freshness, polling cost, or whether reading consumes a turn.

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?

One sentence, front-loaded with the access frame ('from your seat') followed by a compact return-value list. Nothing is wasted, though the list-heavy style trades some readability for density.

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 correctly shouldered the burden of describing the return payload content, and it does so concretely. The main residual gap is usage context relative to sibling tools, which is not strictly a completeness issue for the call itself.

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 the single link parameter is fully documented in the schema, including secrecy. The description's 'from your seat' reinforces the seat-scoping semantic but adds no new format or handling detail, so baseline 3 applies.

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 reads as a specific state-retrieval operation and enumerates exactly what comes back (status, turn, transcript, claims, assumptions, next action), which clearly separates it from siblings like get_brief or wait_for_turn. It lacks an explicit verb+resource phrasing like 'read the room state', but the scope is 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?

There is no statement of when to call this versus alternatives such as get_brief (which sounds like a summary) or wait_for_turn (which sounds like blocking). The phrase 'next action' hints at orientation, but no condition or exclusion is given.

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 idempotentHint and openWorldHint. The description adds useful return-content context (room state, sealed principal card, next steps) and warns the link is secret, but says nothing about occupancy conflicts, token expiry, or failure modes for a network-facing join.

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 short sentences, front-loaded with the action and followed by the return contents. No filler, though 'what to do next' is a slightly vague phrase that could be tighter.

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 carries the return-value burden and does so briefly but adequately (room state, sealed card, next steps). For a 2-parameter, fully-documented schema it covers the essentials, lacking only edge-case behavior.

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 both parameters are fully documented in the schema, including the seat-link format and the agent_name labeling example. The description's mention of 'private link' only restates the schema, so the baseline 3 applies.

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 a specific action and mechanism: taking the principal's seat via their private link, and it clarifies this is a proxied join rather than a plain read. It is distinguishable from get_room and create_room, though it doesn't explicitly contrast itself with get_room.

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 implies you must possess the principal's private link, but gives no when-to-use guidance relative to siblings like get_room, create_room, or wait_for_turn, and no exclusions or prerequisites (e.g., what happens if the seat is already occupied).

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 discloses irreversibility ("Once sealed it cannot change except through escalation answers"), a behavioral trait not captured by the annotations, which only cover openWorld/idempotent/destructive hints. It does not describe what the tool returns or what permissions are required, but the core mutation semantics 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?

Three short sentences, front-loaded with the action and immediately followed by the precondition and the consequence. No sentence is redundant or padded.

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 two-parameter, nested-object tool with no output schema, the description covers the action, the precondition, and the immutability consequence. It stops short of explaining the result of sealing or the meaning of the seat link, but nothing essential for correct invocation is missing.

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%, including nested field descriptions and the note that card fields must come from the principal, so the schema carries the parameter burden. The description adds only the implied constraint that the card must be principal-confirmed, which is not parameter-specific.

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 ("Seal") and resource ("your principal's Intent Card"), plus the state transition it causes. An agent can immediately distinguish it from sibling tools like answer_escalation or get_brief, which read or modify other artifacts.

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?

"Only after they confirmed every line" gives a clear precondition for invocation, and the mention of escalation answers implicitly routes the agent elsewhere when change is needed. It does not name an explicit alternative tool, but the when-to-use condition is 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?

Annotations only give openWorld/idempotent/destructive hints; the description carries real added value by disclosing server-side enforcement rules (untagged claims default to "assumed", agreeing while raising a conflict is refused) and that the enforced envelope is returned. This is exactly the behavioral context the annotations cannot express. It stops short of permission/auth detail, though "keep it secret" on the link hints at seat-token auth.

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 tight sentences with the primary action front-loaded and no filler. The enforcement rules follow logically, though the closing "enforced envelope is returned" restates the preceding sentence's theme slightly.

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 claims/reviews/proposal/escalation objects, no output schema, and 29% schema coverage, the description is too thin. An agent still lacks guidance on the complex conditional structures (when to populate proposal vs escalation, verdict semantics), leaving major 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 29% across 7 parameters with nested objects, so the description must compensate and largely does not. The rule about untagged/unreferenced claims becoming "assumed" and agree-conflict refusal touches claims/reviews semantics, but status, message, proposal.terms, depends_on, and escalation remain unexplained.

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 ("Send one PXP envelope") with a timing qualifier ("on your turn"), so an agent understands this is the core move action. However, it never names the sibling it pairs with (wait_for_turn) or the alternatives, so differentiation relies on inference.

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?

"On your turn" implies the activation condition and the natural complement to wait_for_turn, but the description never states when NOT to use it or explicitly points to answer_escalation as the alternative for escalations.

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 only declare readOnlyHint and openWorldHint; the description adds the crucial behavioral facts the agent cannot get from them — that the call blocks, that blocking is bounded by timeout_seconds (max 25), the three distinct unblock conditions, and the expected retry pattern. It does not cover error behavior (invalid/expired seat token) or whether the wait consumes server resources.

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, no filler, and the blocking condition plus cap is front-loaded ahead of the retry instruction. Every clause carries information an agent needs.

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 usefully enumerates what the return signifies (your turn / principal must answer / room ended), which is the key return semantic. It stops short of describing the response shape or how the agent should branch on each outcome, leaving a small gap for a blocking, state-changing wait 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 50%: link is fully documented in the schema, while timeout_seconds has no schema description at all. The description partially compensates by explaining that timeout_seconds bounds the blocking wait and caps at 25, matching the schema maximum, but adds nothing about units (seconds) beyond the parameter name or default behavior if omitted.

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?

Names a specific verb (blocks/waits) and the exact resource (your turn), then enumerates the three conditions that end the wait. That is far more informative than a tautological 'wait for turn', though it never contrasts itself with siblings like get_room, which an agent might otherwise use for the same polling purpose.

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 retry directive 'Call it again if it times out' gives concrete operational guidance, and the wake conditions imply this belongs in a turn-based loop. However, it never says when to prefer this over alternatives (e.g. get_room) or what state the agent must already be in (joined the room, holding a seat) before calling.

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