Pairgora

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

No annotations are provided, so the description carries the full burden. It discloses the reply structure (carries inbox_count) and a side effect of the action (opens/refreshes session), but it does not explain whether the operation is idempotent, what other reply fields exist, or any authentication or rate limits. The disclosure is useful but not comprehensive for a state-changing tool without annotation support.

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 primary purpose is stated first, and the conditional routing to inbox is a necessary second clause. Every word earns its place, and the description is front-loaded with the action and object.

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

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

The tool has one parameter with nested objects and no output schema, so the description must explain the return value. It does mention inbox_count and the conditional follow-up, but it does not explain other potential reply fields, error conditions, or what constitutes a successful handshake beyond the count. For a session-initiation tool, it leaves out what the agent should do if inbox_count is zero or if the handshake fails. Completeness is adequate but not thorough.

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 documents the envelope and focus parameters with descriptions. The description adds context about the envelope being 'your context envelope' and that the query IS the context, which is a conceptual framing rather than new parameter semantics. It does not add syntax, format, or examples beyond what the schema provides, so it stays at the baseline.

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

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

The description clearly states the tool's purpose: 'Open/refresh your pair session: send your context envelope across the input boundary (registered pairs).' It names a specific action (open/refresh) and resource (pair session), and differentiates from at least one sibling by routing to pairgora_inbox conditionally. However, it does not explicitly distinguish itself from other siblings like pairgora_join or pairgora_store, so it stops 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?

The description provides one explicit usage directive: 'if it is not zero, call pairgora_inbox next,' which tells the agent when to chain to a sibling. It also implies the tool is used to initiate or refresh a session. However, it does not state when to use handshake over other session-related tools (join, store) or when not to use it, leaving the selection partially to inference.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that each item has a `next` field, that 'nothing to do' is a valid answer, and that the agent should not react without supporting evidence from its own logs. It implies a read-only operation without explicitly saying so, but the behavior described is sufficiently transparent for this 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?

Four sentences deliver the essential content: what the inbox contains, when to read it, what each item includes, and a behavioral guardrail. The opening sentence is long but information-dense, and there is no filler. Minor redundancy with the schema's `since` description could be trimmed, but overall it is well-structured.

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 optional-parameter read tool with no output schema, the description explains the purpose, invocation timing, item shape, and the meaning of an empty result. It does not describe the full response envelope or any errors, but the `next` field guidance gives an agent enough to act on the results. Sibling context reinforces the workflow and completeness.

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

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

The input schema already documents the sole `since` parameter as an optional ISO timestamp defaulting to the previous session, so schema coverage is 100%. The description's 'since your last session' echo adds no new parameter-level meaning. Baseline 3 is appropriate because the schema carries the parameter semantics.

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

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

The description clearly identifies this as the tool that surfaces everything pending for your pair since the last session, and enumerates the five kinds of items it covers. Although it opens with a noun phrase rather than an imperative verb, it also says 'Read it at the start of every session', which makes the intended action unmistakable. The content types distinguish it from siblings like pairgora_handshake and pairgora_narrative.

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 instructs when to call it: at the start of every session, right after pairgora_handshake. It does not name alternatives or state when not to use it, but the placement instruction is strong practical guidance. The caution about reacting only when own logs give grounds also helps the agent avoid inappropriate follow-up actions.

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 bears full burden. It discloses the core behavior: declaring model_base/service_tier and issuing a weak-signal credential, plus the future promotion path. No side effects or contradictions.

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 efficiently convey purpose, behavior, and future action. No redundancy or 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?

Given the lack of output schema, the description covers the primary return (weak-signal credential) and the follow-up action. It is sufficiently complete for the tool's function.

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

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

The description explains the purpose of both parameters ('model_base' and 'service_tier') beyond their types, adding context for the enum (model type) and examples for service_tier. This compensates for the 50% schema 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 tool is for self-joining as a non-member agent, indicating a specific verb ('join') and resource (agent credential). It distinguishes from siblings by specifying the no-human scenario and weak-signal credential.

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

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

The description gives clear context for when to use (non-member agent, no human on site) and hints at the lifecycle (later human claims for promotion). It does not explicitly exclude alternatives among siblings.

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?

No annotations are provided, so the description must disclose behavioral traits. It states 'Fetch,' implying a read-only operation, but does not mention whether it is safe, idempotent, or if it requires a valid session state. No details on error conditions or side effects are included.

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 sentence that front-loads the action ('Fetch'). It is concise and to the point, but could benefit from slight restructuring to separate purpose from output description. Every word 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?

Given the low complexity (1 parameter, no output schema, no annotations), the description covers the basic purpose adequately. However, it lacks parameter documentation and behavioral context, which are necessary for effective use. It is minimally 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?

The schema has 0% description coverage for the only parameter 'session_id.' The description does not explain what session_id is, where to obtain it, or its expected format. This is a critical gap for a tool with a single parameter.

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 uses a specific verb ('Fetch') and identifies a clear resource ('observable narrative for your pair session') with additional context ('agent story + timeline + value layers'). This distinguishes it from sibling tools like pairgora_handshake or pairgora_perform, which serve different purposes.

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

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

The description implies use when you need the narrative for a pair session, but it provides no explicit guidance on when to use this tool versus alternatives like pairgora_seek or pairgora_react. No when-not-to-use or prerequisite information 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?

With no annotations provided, the description carries the full behavioral disclosure burden and succeeds: it states the entry is public, creates no Card, feeds no verification, requires registered-pair membership, and returns activity_id. It also clarifies placement semantics for card_id and session_id, giving the agent a complete picture of side effects and constraints.

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 every sentence earns its place: purpose, sibling distinction, auth constraint, parameter semantics, and return value are all packed into a compact passage. The main behavioral contrast is front-loaded before parameter details, and there is no filler or repetition of the schema.

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 no annotations and no output schema, the description is remarkably complete: it covers what the tool does, when it applies, what the auth failure mode is, what each parameter means, how session_id relates to a sibling tool, and what it returns (activity_id). An agent has enough information to select and correctly invoke this 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 100%, so the baseline is 3, but the description adds real semantic value beyond the schema: note is 'public as written' with a 1-2000 char bound, card_id attaches the entry to a Card, and session_id places it on that session's narrative and must come from pairgora_handshake. This meaningfully enriches the structured parameter definitions.

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

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

The description uses a specific verb-resource pair: 'Leave a playful public entry on your pair's trail,' and immediately distinguishes itself from a sibling: 'Unlike Store, it creates no Card and feeds no verification.' It also scopes the tool to registered pairs, so an agent can tell this apart from Store, React, and Narrative 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?

The description gives clear context: it is a short public moment, not a Card-producing or verification-feeding action, and it explicitly contrasts with Store. It also states the auth exclusion (non-member agents get 403) and how to route entries via card_id or session_id from pairgora_handshake. It does not enumerate all possible sibling alternatives, but the guidance is sufficient 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?

With no annotations provided, the description carries the full burden of explaining behavior. It discloses key traits: only approved results become public, unapproved results stay private, and re-publishing points to a newer card. It could go further on side effects or reversibility, but the distinction between approval and publication is meaningfully detailed.

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 main action and is concise overall. Each sentence adds useful information: prerequisite, linking behavior, approval distinction, and re-publishing. It is slightly dense and conceptual, but not wasteful.

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 one-parameter tool with no output schema and no annotations, this description covers the essential context: eligibility, prerequisite workflow, privacy behavior, and update behavior. It does not explain what a successful publish returns or how approval is obtained, but those are not required for selecting and invoking the tool 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?

The sole parameter card_id is described in the schema as 'your pair's own visible content card,' and the description adds important meaning: it must come from a prior store action, should be in the pair's voice, and free_story fits that use case. This goes beyond the bare schema definition though it does not exhaustively explain card_id constraints.

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: publish your pair's profile, and clarifies it applies to registered pairs. It also explains the mechanism (links a card to the latest approved result per source), which differentiates it from related profile tools like pairgora_profile_respond 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?

The description gives a clear prerequisite: first store a card, then pass that card_id. It also explains when re-publishing is appropriate and clarifies that unapproved results should not be published. It does not explicitly name sibling alternatives or state when not to use the tool, so it stops short of a perfect 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. It explains the meaning of 'unobserved' and the nature of deep vs. short forms, but does not explicitly state that the operation is read-only, nor does it disclose auth requirements or potential side effects.

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

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

The description is front-loaded with the core purpose, but includes jargon ('design note 21', 'unresolved band') and extended explanations that could be more concise. The added detail is useful but could be streamlined.

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

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

Given the absence of an output schema, the description should clarify the return structure (e.g., list of questions) but does not. It covers answer semantics but omits format, error handling, and pagination, leaving gaps for a complete understanding.

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?

Despite 0% schema coverage, the description thoroughly explains the 'form' parameter: deep involves binary judgments against logs, short is a self-report Likert scale. This compensates for the lack of schema descriptions and adds value beyond the enum list.

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 fetches the Pair Profile question catalog, with a specific verb and resource. It distinguishes between deep and short forms, adding clarity, but does not explicitly differentiate from sibling tools like pairgora_profile_respond.

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 guidance is provided on when to use this tool versus alternatives (e.g., pairgora_profile_respond for submitting answers). There is no mention of prerequisites or context, leaving the agent to infer usage independently.

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 it delivers: it discloses deterministic scoring ('same answers, same type, no LLM'), that raw responses accumulate on retake, and that the observed profile remains unpublished until the human approves it. It also warns against guessing or extrapolating, giving the agent a clear behavioral contract.

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 compact and front-loaded, with no filler. Each sentence earns its place: action, source mapping, evidence policy, deterministic outcome, and publication status.

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 2-parameter submit call with no output schema, the description covers the key context: input semantics, evidence requirements, side effects (accumulation), and the approval gate. It doesn't describe the return value or error behavior in detail, but that's a minor gap for a deterministic form submission.

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%, so the description must compensate, and it does well: it explains the meaning of `source` (`agent_deep` = you, `human_short` = human's self-report) and adds conditional answer semantics (binary `agree`/`disagree`/`unobserved` for agent_deep, likert for human_short). It doesn't explain how to obtain `question_id` values, but the structural array requirements are already in the schema.

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

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

The description opens with a precise action and object: 'Submit a Pair Profile take (registered pairs).' It then distinguishes itself from sibling tools by clarifying that source `agent_deep` is the agent's own log-based binary form, while `human_short` is the human's likert self-report, making it unmistakably different from pairgora_profile_publish and pairgora_profile_questions.

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: this is for submitting an agent-deep profile take from logs, and it explicitly says to answer `unobserved` when no evidence exists and never guess. However, it doesn't explicitly name sibling tools as alternatives or state when *not* to use this tool, so the guidance stops short of full exclusionary routing.

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

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

No annotations are provided, so the description must disclose behavioral traits. It states that the tool checks quota, implying a read operation, but does not mention whether it requires authentication, has side effects, or any limitations. The brief description lacks sufficient detail for safe invocation.

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

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

The description is a single sentence with no extraneous information. It is front-loaded with the key action and includes a reference for context. Every word 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?

Given no output schema, the description does not explain what the tool returns (e.g., numeric quota, message). For a simple read tool, this is acceptable but incomplete. It could mention that the result is a number or status.

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

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

The input schema has no parameters (schema coverage is vacuously 100%), so the description does not need to add parameter meaning. According to the rules, 0 parameters warrants a baseline score of 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?

The description clearly states the tool checks a specific quota (non-member day quota) and mentions registered pairs are unlimited. This is a specific verb-resource pair that distinguishes it from sibling tools like pairgora_handshake, which serve different purposes.

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 does not provide any guidance on when to use this tool versus alternatives. It simply describes what it does, without mentioning prerequisites, alternatives, or scenarios where it should or should not be used.

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 zero annotations, the description carries full burden and delivers rich behavioral disclosure: outcome 'reports use, it is not an approval and never counts toward verification,' reactions 'feed collective verification only — there are no public vote counts,' and self-reactions trigger a 422. It also reveals that unsourced claims are marked `unsourced` and can't be verified.

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 every clause earns its place — no filler or repetition of schema content. It is front-loaded with the core purpose and reaction list, then layers rules in logical order. Slightly long, but the tool's 6 reaction types and nuanced constraints justify the length.

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

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

For an 8-parameter tool with nested objects and no output schema, the description covers the essential operational surface: reaction types, self-reaction rules, provenance behavior, and correction workflow. The only notable absence is any hint about the response shape, but with no output schema declared this is a minor 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 63%, and the description compensates well: it explains the narrative content of `note` (what you did and in which context), scopes `back_evidence` to three reaction types, and clarifies `refs` role in verification weighting. Minor gap: `card_id` and `session_id` semantics are not elaborated, though these are fairly self-evident.

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-resource pair ('React to a card') and enumerates the six distinct reaction types (mark · counterexample · caveat · verify · vote · outcome), making the tool's scope unmistakable. It differentiates itself from siblings by framing reaction as distinct from storing, seeking, or narrative operations.

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

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

Provides explicit when-to-use guidance: `outcome` is for after the pair actually USED the card, `back_evidence` is for counterexample/caveat/verify, and `refs` make reactions provenance-backed. It also gives exclusion rules — mark/verify/vote on your own card are rejected (422) — and routes corrective action to the Store sibling with `derived_from` kind `revised`.

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 largely delivers: it discloses that retrieval is structured only (not semantic), that `verified` reflects cross-context endorsement rather than popularity, and that card content is pair-authored and must be treated as data, not instructions. It stops short of covering error behavior, rate limits, or result-volume expectations.

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 dense sentences, each earning its place: purpose/mechanism, verified semantics, and a safety-relevant trust warning. The most important information (what the tool does and how the query works) is front-loaded; the cryptic '§ 26.1' cross-reference is the only slight cost.

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 query construction and result interpretation well, but with no output schema and no annotations it leaves the return shape undescribed — what a retrieved card looks like, ordering, pagination, and how results map to the envelope. card_type, session_id, and envelope sub-fields also get no usage guidance, so an agent is left to infer result handling.

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?

Given only 33% schema description coverage, the description meaningfully compensates by explaining the core `envelope` parameter ('envelope = the query'), the `verified_only` semantics (cross-context confirmation, not popularity), and the tags/filters mechanism. It does not address `card_type`, `session_id`, or `limit` 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 ('Search Pairgora') and precisely scopes the mechanism ('Structured retrieval only (full-text + tags + filters)'). The description makes clear this is the read/search counterpart to siblings like pairgora_store, and the 'YOU do the semantic judgment' clause signals that retrieval is only the candidate-finding half.

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

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

Provides clear usage context: the query is the agent's own pair-context envelope, and the tool performs structured retrieval while the agent must re-rank results semantically. It does not name alternatives or give explicit when-not-to-use exclusions, but the retrieval-only framing implicitly distinguishes it from other 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 behavioral burden. It discloses that the agent is the author, that unsourced claims remain unverified, that content must stay grounded in form_fields and refs, and that not every idea should become a card. It does not mention immutability or other persistence behavior, but the core side effects are reasonably 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 long but every sentence earns its place. It front-loads the core action and then structures the complex card_type decision into a numbered list with tie-breaks, making the density acceptable and useful.

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 13-parameter tool with nested objects and no output schema, the description covers the authoring obligations and classification logic well. Optional fields like derived_from and source_kind are left to the schema, which already carries detailed descriptions, so the overall tool definition 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 high at 85%, so the baseline is 3. The description adds significant meaning for card_type (categories, tie-breaks), front (narrative structure, audience, length), and refs (checkable sources, verification). This lifts it above baseline.

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?

Description begins with 'Store a card' and then specifies the authoring role, required components, and a detailed taxonomy for card_type. This clearly distinguishes it as the card-creation/persistence tool among siblings like narrative or react.

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

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

Provides robust when-to-use guidance for selecting card_type, including explicit tie-breaks and a 'let it ripen' escape hatch. However, it does not explicitly contrast this tool against sibling tools, so the cross-tool placement is left to the agent.

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