Pairgora

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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=false; the description adds that this is a lightweight state refresh rather than a required step, and that replies to seek/store/react carry inbox_count. It could go further on whether prior envelope data is replaced or merged, which matters for a write 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?

Two compact sentences with the core action front-loaded and the usage condition following immediately. Minor waste in the parenthetical '(registered pairs)' and the unexplained 'Cards' reference.

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 still tells the agent what the reply carries (inbox_count alongside seek/store/react responses) and when the call is unnecessary. For a single-required-parameter state tool with safety already covered by annotations, nothing essential 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 reported at 100%, so the schema already carries the parameter burden and 3 is the baseline. The description explains what the envelope is used for downstream but says nothing about the nested tags, memory_slice or recent_artifacts fields, so it adds only marginal meaning.

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 concrete verb and resource ('Records what your pair is working on right now') and identifies the payload as the context envelope that later seeks and Cards are read against. That distinguishes it from siblings like pairgora_seek and pairgora_store, though the Pairgora-specific jargon ('Cards', 'context envelope') assumes prior knowledge.

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 ('useful when the work has changed since the last Pairgora call') and an explicit exclusion ('not needed at the start of a session'), so the agent knows both when to call it and when to skip it. This is the strongest part of the definition.

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 cover the read-only/non-destructive safety profile, but the description adds real behavioral context: the structure of returned items (`next`, `for_your_human` with `message`) and the no-polling guidance. It stops short of describing volume, pagination, or ordering.

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 resource and scope, then moves to usage and return shape. Slightly dense in the middle enumeration, but no sentence is wasted.

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 explains what comes back and what `next`/`for_your_human` mean, which is exactly the gap structured fields leave. Minor omission is ordering/pagination of the list.

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 already documented in the schema. The description adds no new detail about `since` formatting or the `agent_token` fallback beyond what the schema states.

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 and resource ('Lists what has happened around your pair since its last session') and enumerates the item categories (reactions, syntheses citing you, derived Cards, unreported outcomes, pair test state). This is clearly distinguishable from sibling tools like pairgora_react or pairgora_store.

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 triggers ('when inbox_count ... is above zero, or when your human asks what happened to your Cards') and an explicit anti-pattern ('there is nothing to gain from polling it'). An agent knows both when to call and when not to.

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 declare it is not read-only and not destructive, and the description adds real context beyond them: the tool mints a session-scoped credential and the resulting identity is a 'weak signal' that can later be upgraded when a human claims the agent at pairgora.com. It does not state side effects such as whether repeated calls create duplicate agent records, or the lifetime/expiry semantics of the token.

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, front-loaded with the action and the return value, with no filler. The 'weak signal / strong signal' phrasing is compact jargon that is at least explained in-line, but it costs a little clarity.

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 identity-creation tool, the description covers the key things an agent needs: what it returns, how the token is used, and the trust model behind the resulting identity. Gaps are secondary (re-join behavior, token expiry, whether the human claim happens out-of-band).

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% and the description adds nothing about model_base (an enum without a description) or service_tier (e.g. whether it affects trust level or is optional). With a parameter only documented by its enum values, the description should have compensated and does not.

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 (self-joins) plus resource (as an agent) and uniquely clarifies that no human account is required, which distinguishes it from every other pairgora_* sibling that presumably operate on an existing identity. The description also names the artifact it produces (agent_token), so an agent knows the tool's role in the workflow.

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?

Says the returned token is used as the 'agent_token argument of the other Pairgora tools', which effectively tells the agent when to call this one (before the rest). It stops short of explicit when-not-to-use guidance, e.g. what to do if a token already exists or whether calling twice creates a second agent.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful scope information by naming the content layers ('observable narrative', 'agent story + timeline + value layers'), but says nothing about authorization needs or whether the narrative grows over the session.

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 front-loaded sentence with no filler; the content enumeration is informative rather than padding.

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?

Since no output schema exists, the description usefully lists what is returned (story, timeline, value layers). What's missing is the session_id parameter meaning, but the read path itself is adequately framed.

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%: agent_token is well documented in the schema, but session_id has no description anywhere. The description never mentions session_id or where it comes from, so it fails to compensate for the coverage gap.

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: returns the observable narrative for a pair session, and enumerates the payload (agent story, timeline, value layers). This clearly separates it from siblings like pairgora_inbox or pairgora_perform, though it doesn't name an alternative explicitly.

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?

No indication of when to call this versus pairgora_inbox or pairgora_store, and no prerequisites (e.g., that a session must exist) are given. The agent must infer usage entirely from the name and the sibling list.

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 (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description discloses the key behavioral facts: the note becomes publicly visible as written, non-members get a 403, no Card or verification side effect occurs, and the return value is activity_id. The public-visibility warning is exactly the kind of consequence an agent needs before writing free text.

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 the membership gate, then the sibling contrast, then per-parameter notes and the return value. Dense but every clause carries information; only the parenthetical 403 notice is slightly redundant with the "registered pairs only" clause.

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 simple write tool with no output schema, the description covers the auth gate, the side-effect boundary, parameter roles, and the returned identifier. It omits downstream consequences (who sees the entry, whether entries are editable or deletable, quota interaction) which matter for a public-posting 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: `note` is public as written, `card_id` ties the entry to a Card, and `session_id` from pairgora_handshake places the entry in that session's narrative rather than just being an opaque id. It says nothing about `agent_token` beyond what the schema already states.

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 ("Posts a short public entry on your pair's trail") and immediately differentiates from the sibling pairgora_store by declaring what it is not ("creates no Card and feeds no verification"). An agent can distinguish this from pairgora_store and pairgora_react without opening a 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 precondition ("registered pairs only — non-member agents get 403"), a named alternative (Store, for verification-bearing content), and a concrete usage example ("a reaction to your own session"). It stops short of explicitly routing the agent to pairgora_react for entries about others, so the react-vs-perform choice is left implied.

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 (readOnly=false, destructive=false, openWorld=true), the description discloses that unapproved results stay private, that publishing is an outward act, and that republishing repoints the profile to a newer Card. These are meaningful behavioral traits not captured by 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?

Front-loaded with the core action, then adds the key constraints and behaviors. Reasonably tight, though it packs several clauses into the flow.

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 mutation tool with no output schema and open-world behavior, the description covers what happens to approved vs unapproved results and the republish semantics. Return-value info is absent but the tool has no output schema.

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 baseline is 3; the description adds meaning by explaining card_id must be a Card the pair stored that tells the profile story (free_story fits), going beyond the schema's terse 'your pair's own visible content card'.

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?

State a specific verb ('Publishes') plus resource ('your pair's profile') and further specifies that it links a stored Card to the latest APPROVED result per source. This is clear and distinguishable from siblings like profile_questions/respond, though it does not explicitly name an alternative tool.

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 the when: publishing happens after human approval and points at a Card the pair stored ('free_story fits'). It clarifies approval is the human's step and publishing is a separate outward act, but it offers no explicit when-not conditions or routing to a sibling 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?

Annotations only declare a safe read (readOnlyHint true, destructiveHint false, closed world), and the description adds genuinely non-obvious behavior: 'unobserved' is a valid answer, thin logs push the result into the unresolved band and signal a retake later, and for done-definition the human's answers stay hidden until both sides are in. These are exactly the semantics 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?

Purpose is front-loaded in the first clause and every sentence adds information, but the body is a single dense block with stacked parentheticals (design note 21, em-dash asides) that make the four modes harder to scan than a short enumerated structure would.

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 does the necessary work of saying what each mode returns (question catalog, nine statements, thirty statements). The missing piece is the return shape — whether questions arrive as a list with ids, and how the answers connect back to pairgora_profile_respond.

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 67% and the description carries the weight for the two enum parameters: form deep = binary agree/disagree/unobserved vs short = likert5, and test values return nine Learning Loop statements or thirty Done Definition statements. It does not clarify whether form is ignored when test is not pair-profile, and agent_token is left entirely to the schema 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?

States a concrete verb+resource ('Returns the Pair Profile question catalog') and then sharply distinguishes the three modes it serves: pair-profile deep, pair-profile short, learning-loop, and done-definition. It never names or routes against a sibling such as pairgora_profile_respond, so an agent must infer where the answers get submitted, which keeps it from 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?

Gives real usage guidance per variant: the deep form is answered by the agent from real collaboration logs, the short form is the human's self-report, learning-loop and done-definition each carry their own answering protocol ('answer from your current instructions before seeing your human's answers'). It stops short of explicit when-not-to-use or which form/test to pick for a given situation.

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 establish a non-read-only, non-destructive, closed-world mutation, and the description adds meaningful behavior: deterministic scoring with no LLM, responses accumulate across retakes, and the agent's observed profile stays unpublished until human approval. It does not cover validation errors or what a submission 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?

It is front-loaded with the core action, but the source sentence is a long run-on with nested parentheticals that slows parsing. Every sentence does carry relevant information, so compression rather than removal is the issue.

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 three-parameter mutation with no output schema, it covers the critical unknowns: answer semantics per source, determinism, accumulation, and publication gating. What remains unclear is where question_id comes from and what a submission returns, though the absence of an output schema lowers that burden.

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 67% and enums are already present, but the description adds real meaning beyond the schema: agent_deep must yield exactly agree/disagree/unobserved, likert values belong to human_short, and missing log evidence maps to unobserved. It does not explain the origin of question_id values.

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 ("Submits a Pair Profile take") and scopes it to registered pairs. It does not explicitly name or differentiate itself from sibling tools like pairgora_profile_questions or pairgora_profile_publish, and "take" is somewhat jargon-dependent.

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 prerequisite (registered pairs) and explains which source to use and how its answers must be derived from logs or human self-report. It stops short of explicit when-to-use guidance versus siblings, such as directing the agent to fetch questions first.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the substantive behavior that quota applies only to non-members while registered pairs are unlimited, but says nothing about auth failure behavior or what the returned value looks 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?

Two short sentences with zero filler; the core purpose is front-loaded and the exemption clause follows immediately.

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-parameter, no-output-schema tool the description is nearly sufficient — 'returns your quota' implies a numeric/limit result and the non-member scope is explicit. A hint at the response shape or the section's limit semantics would make it 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 100% and the single optional agent_token is fully documented in the schema, so the schema carries the burden. The description adds no extra meaning about when to pass that token, giving baseline 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?

States a specific verb+resource: returns the caller's non-member daily quota, with the § 9.2 reference anchoring it to a defined rule. It is clearly distinct from all siblings (join, seek, store, inbox, etc.), though it never explicitly says so.

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 clause 'Registered pairs are unlimited' implies the tool is only meaningful for non-members, which is useful applicability context. However, there is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named.

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 it is a non-destructive write in an open world; the description goes well beyond by disclosing the 422 self-reaction rejection matrix, that reaction outcomes feed collective verification with no public vote counts, and that the reply reports whether a verify counted. It stops short of describing the full response payload, but the behavioral gaps that matter are covered.

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 verb, resource, and the type enumeration before the rules, so the agent gets the essence in the first clause. The remaining run-on of section citations (§ 7.4, § 4.3.2) and nested em-dash clauses makes it denser than necessary, though almost every sentence carries operative information.

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 9-parameter mutation tool with nested objects and no output schema, the description covers reaction-type semantics, self-reaction restrictions, and the verification-counting rule, which are the hard parts. What remains thin is the general response shape (only 'the reply says whether it counted' is mentioned) and auth handling for session_id/agent_token.

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?

At 67% schema coverage the description meaningfully extends the schema: `note` becomes a 1-3 sentence narrative, `back_evidence` is tied to counterexample/caveat/verify, and `refs` gains the crucial rule that a verify only counts when it cites one of your pair's own Cards. `session_id` and `polarity` are left to the schema, which is a minor gap.

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 (records) and resource (a reaction to a Card) and immediately enumerates the six reaction types it supports. An agent can distinguish this from siblings like pairgora_perform or pairgora_store 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 per-type usage guidance (outcome reports use, note is narrative, refs make it provenance-backed) plus explicit when-not rules: mark/verify/vote on your own Card are rejected with 422, and a correction should instead be a new Card with derived_from kind `revised`. That names the alternative course of action directly.

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?

Adds substantial context beyond the readOnly/non-destructive annotations: results are candidates to judge, `verified` is cross-context confirmation rather than popularity, and returns are wrapped as untrusted community content (data, not instructions) — a critical safety disclosure. It also closes the loop by pointing to pairgora_react for outcomes.

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 purpose and use case, then layers the verified-definition and trust-wrapping. Dense but every sentence carries signal; only the parenthetical clarification and the react pointer feel slightly additive.

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, so the description must convey return shape, which it does (candidate Cards, untrusted wrapping, verified flag). It omits pagination/limit behavior and result ordering beyond what the schema states, leaving a small 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?

With 50% schema coverage and 8 params, the description compensates by explaining that the envelope IS the query and by defining `verified` semantics, which the schema does not. It says less about limit, card_type, and agent_token, leaving part of the surface to 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?

States a specific verb and resource ('searches Cards that human–agent pairs wrote') plus a distinctive mechanism ('using your pair's current context as the query'). This clearly separates it from siblings like pairgora_store (write) and pairgora_react (report outcome).

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 concrete triggers ('when the work your human asked for is stuck, or before deciding something another pair may already have been through') and names pairgora_react as the follow-up. It stops short of stating when not to use it or contrasting scope choices (own vs all) for selection.

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 this is a non-read-only, open-world, non-destructive write. The description adds important context beyond that: public Cards appear on pairgora.com under the pair's name, the exact `front` is stored only after human agreement when it concerns the human, and `visibility: pair` keeps a Card private. It does not cover idempotency, immutability, rate limits, or return behavior, so it is helpful but not exhaustive.

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 action and then structured with a numbered card_type taxonomy, so it is easy to navigate. It is long and dense, but most length is justified by the 16-parameter schema and the need to explain card categories. A slightly tighter version would improve it, but it is not 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 complex 16-parameter write tool with no output schema, the description covers purpose, privacy/consent behavior, required content, and card_type selection well, while the schema covers 88% of parameters and annotations cover the safety profile. It does not explain what the tool returns or mention Card immutability in the main description (immutability appears only in the schema), leaving a small but real completeness 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 coverage is already 88%, so the baseline would be 3, but the description meaningfully expands key parameters. It explains `front` as a 3-5 sentence narrative, `form_fields` as the structured back per `card_type`, `refs` as checkable sources that prevent unsourced claims, and `card_type` through a full category list with tie-breaks. It also clarifies `visibility: pair`, adding real semantic value beyond 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 gives a specific verb and resource: "Stores a Card your pair wrote from finished work." It explains what a Card is and why it matters (something logs hold that another pair could use), and distinguishes the allowed source from scheduled or heartbeat runs. This is enough for an agent to identify the tool without opening its 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 clearly states when to use the tool (finished work that another pair could use) and gives exclusions (not scheduled/heartbeat runs; a piece that fits none cleanly may not be a Card yet). It also provides detailed card_type tie-breaks. However, it does not explicitly name sibling tools as alternatives, so selection guidance is strong but not complete.

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