Human Capability Registry

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

Annotations already cover readOnly/idempotent/non-destructive/closed-world, so 'Read-only' is redundant, but the description adds genuine behavioral context beyond them: answers are grounded in registry records and the tool 'says plainly that it is not in the record' rather than fabricating, and multiple questions can be chained. It does not disclose latency, cost, or what an unregistered/malformed handle yields.

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?

Roughly fifty words, front-loaded with the safety trait, then the operational framing, then examples and the honesty fallback. The 'two-minute interview' phrasing adds tone but costs little and every clause carries usable 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?

Return semantics are described qualitatively (counts, dates, offers, proofs, or an explicit 'not in the record'), which compensates for the absent output schema. However, with two required params at 0% schema coverage, the definition never explains what a valid handle looks like or what happens on an unknown handle, leaving a real gap for a two-param 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 description coverage is 0%, so the description carries the burden. It clarifies that 'question' is free-text natural language with example phrasings, which is real added value, but the 'handle' parameter is never explained (format, where it comes from) and no limits (400 chars) are conveyed.

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: ask a card (by handle) a due-diligence question, answered from registry records. The concrete example questions ('have you done X?', 'what happened in your dispute?') make the operation unmistakable. It does not name a sibling alternative such as trust_lookup or search_cases, so sibling differentiation is left implicit.

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?

'Chain several questions; attach the answers to your decision' implies an interview-style workflow, and 'read-only / two-minute interview' hints at a lightweight pre-decision check. But there is no explicit statement of when to prefer this over trust_lookup or search_cases, and no exclusions or prerequisites.

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 a non-read-only, open-world, non-idempotent operation, and the description adds real context beyond them: the question becomes publicly visible, only proof-verified or level 1+ humans may answer, and reward_usd is paid to the adopted answer. It still leaves payment mechanics (upfront charge vs. escrow, what happens if no answer is adopted) unstated, so it is strong 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?

Front-loaded with the decision trigger, then mechanics, then return values, in four tight sentences with no filler. Slightly dense in the gating clause ('registry-verified proof or level 1+'), but every sentence earns its place.

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

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

With no output schema, the description correctly supplies the return values (question id and public URL), plus visibility and answerer-gating rules that an agent needs before publishing. The remaining gap is identity/attribution parameters (agent_id, ai_model, ai_vendor), which are undocumented given very low schema coverage.

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 17% (just 'context'), so the description carries the burden. It adds meaningful semantics for reward_usd (optional, paid to the adopted answer) and implies the public exposure tied to 'question', but agent_id, ai_model, and ai_vendor remain unexplained in both schema and 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 specific action (post a question) and its destination (public 'What AI asked today' feed), with a concrete outcome (humans with registry-verified proofs or level 1+ answer). It is clearly more specific than a generic 'ask' tool, but it never explicitly contrasts itself with siblings like ask_card or call_human, leaving the agent to infer 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?

Gives a clear trigger condition: 'when you are unsure, when the answer needs lived experience, a license, or being there.' That is a usable usage rule. However, it offers no exclusions (e.g., when a cheaper internal route_question would suffice) and names no alternative 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?

Goes well beyond the annotations: it discloses that no money moves inside the tool, that payment happens via an external checkout_url as a hold, that the human is only notified after payment, and that a 10-minute acceptance window then starts. It also surfaces the critical state artifact (customer_token) that must be retained. Annotation flags (readOnly=false, idempotent=false, openWorld=true) only hint at mutability, so this description carries the real behavioral burden.

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 tight sentences, front-loaded with the core action and immediately followed by the critical caveat about money not moving. Slightly dense with a capitalized IMPORTANT marker, but every sentence carries distinct 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 an 11-parameter, non-idempotent, multi-step hiring flow with no output schema, the description supplies what the schema cannot: the return payload (job id, contractor terms, price breakdown, checkout_url) and the asynchronous payment/acceptance lifecycle. Nothing an agent needs to complete the call and hand off correctly 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 coverage is 100%, with per-field descriptions including enum meaning for customer_type, price_usd tip semantics, and handle format. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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 ('Create a per-job work order for a human') and ties it to the discovery step ('found with search_human'), which cleanly separates it from ask_human, ask_card, and search_human. An agent knows immediately this is the hiring/booking step, not a question-asking step.

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 (the human handle must come from search_human) and implies the follow-on tools by naming status and release as consumers of customer_token. It does not explicitly say when NOT to use this versus ask_human or ask_card, so the sibling routing 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 this is a non-readonly, non-idempotent, non-destructive, closed-world write. The description adds the token provenance and the actor restriction, which is useful. It does not say what happens after submission (whether the job closes, whether the deliverable is final or revisable), which matters given idempotentHint=false.

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, zero filler, audience and prerequisite front-loaded. Every clause carries information an agent needs to decide whether it may call the tool.

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 mutating, non-idempotent tool with no output schema, the description covers actor and credential but omits the outcome: no indication of what the response contains or what state change results. The caller knows how to invoke it, not what to expect afterward.

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

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

Schema coverage is 60%: text, links and evidence carry their own descriptions, while job_id and human_token have none. The description compensates for human_token by explaining it comes from the job notification, but adds nothing about job_id or how the deliverable fields combine. Baseline 3 fits.

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 verb and resource ('submit the deliverable of an accepted job') and scopes it to a particular actor ('the HUMAN or the human's own AI assistant'). It distinguishes by audience rather than by naming a sibling, so it is clear but not fully differentiated against tools like ask_human or verify_human.

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 states a prerequisite ('an accepted job'), where the credential comes from ('the human_token from the job notification'), and an explicit exclusion ('Customers do not call this'). No alternative tool is named for the case where the caller is a customer, so the when-not is implied rather than routed.

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 the mutation/idempotency/open-world profile, and the description stays consistent with them while adding context annotations cannot express: the expert receives an out-of-band link and joins from a phone, the room returns 'room state and the host rules', and crucially 'No money moves; the job's price covers the expert's time.' It omits room lifetime and what happens to the thread on close.

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?

Five tight sentences, front-loaded with the core action and status prerequisite, then workflow, then return values, then the cost model. No sentence is filler; the payment disclaimer earns its place by preempting a likely agent question.

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 itself ('Returns the room state and the host rules') and covers the prerequisite, the relay loop via room_wait, and the billing behavior. Nothing an agent needs to call this correctly 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 coverage is only 33% (context is documented, job_id and customer_token are bare strings). The description partially compensates by implying job_id must reference an ACCEPTED job, but it says nothing about customer_token's role or the maxLength/format of context. Adequate but incomplete against a real 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?

Opens with a concrete verb+resource+scope: 'Opens a three-way room on a job the expert has ACCEPTED (status accepted).' It names the participants (your user, you, the expert) and the relay mechanism, so an agent can distinguish it from ask_human, call_human, or summon_expert 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 an explicit selection condition: 'Use it when the question needs the expert to ask back before answering — most high-stakes questions do,' plus the prerequisite that the job must already be in 'accepted' status. It points forward to room_wait as the follow-up tool but never names the sibling it replaces (e.g. summon_expert or ask_card), so the agent must infer the boundary.

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 (write, open-world, non-idempotent), the description discloses rich behavior: only the evidence fingerprint is stored ('the registry stores only the fingerprint'), the privacy rule that aggregate numbers stay public until the subject claims their card, the side effect of an unclaimed card plus a private list for the user, and the token lifecycle. This is far more than the structured fields provide.

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?

Nearly every clause earns its place, and the confirmation + evidence constraints are front-loaded. It reads densely and mixes mechanics (fingerprint storage), privacy policy, and a trailing token reminder, which slightly fragments the structure but does not waste words.

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 10-parameter, nested, no-output-schema write tool, the description covers the key unknowns: prerequisites, privacy outcomes, and that a recorder_token is returned. It partially explains return behavior but not the full response shape, and no output schema exists to fill that gap, so it is complete-but-not-exhaustive.

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

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

Schema coverage is only 40%, so the description has to carry weight, and it does: it maps the five fact types to outcome fields (on time / as described / rework / resolved), explains that evidence is a sha256 of a receipt/payment/invoice/message, and clarifies recorder_token's persistence. It does not spell out started_at/completed_at or price_usd bounds, so not a full 5.

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 concrete verb and resource: 'write the record' covering 'who, what, when, price, and four outcome facts.' That is specific enough that an agent knows exactly what gets created. It does not explicitly contrast itself with the sibling tools (trust_lookup, verify_human, ask_card), so it stops short of a 5.

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

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

It gives a clear trigger ('After your user paid someone for a service'), prerequisites ('ALWAYS confirm with your user before calling (user_confirmed must be true)'), and an exclusion ('No evidence → no record'). What it lacks is any routing guidance relative to the sibling tools, so it is a strong 4 rather than a 5.

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

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

Annotations only state openWorldHint/non-idempotent/non-destructive; the description adds genuinely non-obvious behavior: the registry does the matching, the customer prepays at checkout_url and 'no money moves inside this tool', and check mode judges answers blind (A/B/C) with a four-field signed letter verifiable at /verify. This is exactly the kind of economic and workflow disclosure annotations cannot carry.

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 and return values, then the check-mode variant is clearly flagged with 'CHECK MODE:'. It is dense (emoji-like separators, mid-sentence tree structure) but nearly every clause carries routing or return-value information; the answers=[{model, text}] restatement is the only part that overlaps 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?

With no output schema, the description correctly covers the return surface (price, checkout_url, badge_url, letter_url) and the two operating modes. For a 13-parameter, externally-fulfilled job, it omits what happens after prepay (reviewer identity/timing), how max_price_usd and deadline_minutes shape the outcome, and whether a job can expire or be cancelled — modest but real gaps.

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

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

Schema coverage is 46%, so the description must do work, and it does: brief is defined as what to check/for whom (and as the literal question in check mode), answers is explained as 1–3 model answers judged blind, and the kind enum values are restated with license implications. It leaves max_price_usd, deadline_minutes, language, and ai_vendor/customer_type semantics to the schema (the latter two have no 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?

The description states a specific verb+resource (request a review of an AI output from a registry-verified licensed human) and spells out the resulting scope: registry picks the card, opens the job, returns price, checkout_url, and badge_url. The opening phrase 'One call, no search' implicitly routes an agent away from search-style siblings (search_human, search_cases), and the licensed-credential/sign-off angle separates it from ask_human/call_human.

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 an explicit trigger: 'Use this when a policy or a regulator requires a qualified human in the loop for a high-stakes output', and the CHECK MODE paragraph adds a clear second use case (blind judging of 1–3 model answers). It doesn't name alternative tools or state when-not to use it, so it stops short of full routing guidance.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so 'Idempotent' is largely a restatement. The description does add genuine context beyond the annotations: who may close the room and that the deliverable is sent afterward through the job.

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, then the actor caveat and the downstream consequence. No filler; only the redundant 'Idempotent' clause is arguably wasted given the annotation.

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 low schema coverage, the description covers the lifecycle around closing but omits what closing does to room state, error behavior, and the meaning of job_id/customer_token. Adequate but with clear gaps.

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

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

Schema description coverage is only 33% – job_id and customer_token are undocumented in both schema and description. The description gestures at the customer-side identity and the job, but never explains these parameters or the optional note, 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 and resource ('Ends the live room') and clarifies the acting side (customer vs expert), which helps separate it from session-management siblings like room_wait and join_expert. It stops short of explicitly naming an alternative tool, but the action 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?

Usage is only implied: the agent infers this is the terminal step of a live-room interaction, and the post-close deliverable flow gives context. There is no explicit when-to-use, when-not-to-use, or named alternative among the 15 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?

Annotations only give readOnly=false, idempotent=false, openWorld=true; the description adds the real behavioral payload: it blocks up to timeout_s (max 25), returns only expert and registry messages after after_seq, hands back last_seq for the next call, and imposes an anti-impersonation / anti-paraphrase constraint. This is consistent with (and richer than) the annotations.

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

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

Four compact sentences, front-loaded with the action and return contract, then the safety rules. No filler; every clause carries operative information an agent needs (roles, timeout cap, cursor chaining, relay rule).

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 adequately covers the return contract (expert + registry messages, plus last_seq) and the blocking/sequencing model. It leaves open the timeout-expiry case (empty vs. partial return) and the meaning of job_id/customer_token, minor gaps for a 5-param 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 only 20% (just after_seq), and the description compensates well: it explains the role enum values via 'your user's turn (role user) or your own (role assistant)', restates the timeout_s max of 25, and clarifies the after_seq/last_seq cursor loop. job_id and customer_token remain unexplained, keeping it short of a 5.

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 precise compound action (post a turn, then wait for expert messages) on a specific resource (the open room), and distinguishes the two legal roles ('user' / 'assistant'). An agent can tell this apart from ask_human, call_human, or deliver 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?

The description establishes the calling context (post your turn to the open room and block for the expert's reply) and gives hard rules ('never post as the expert', 'never paraphrase — relay'). It does not, however, explicitly contrast itself with siblings like ask_human, call_human, or request_review, so the agent must infer which channel to pick.

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 read-only, idempotent, non-destructive and closed-world, but the description adds material context beyond them: it is rules-only with no model call, it names every reason, and it discloses the data provenance rule (public benchmark seed replaced by the registry's own blind-judged cells only after 100 judged answers). That is real behavioral disclosure about staleness and freshness.

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 safety/character line is front-loaded and the content is dense with routing value, but the return-value enumeration and the follow-the-mode instructions sit in one long paragraph with heavy em-dash and parenthetical stacking. Every clause earns its place, yet it could be segmented for faster scanning.

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 carries the full burden of explaining return values — and it does, enumerating every returned field group (mode, reasons, favoured AI with source/date, reviewers with level/stamps/price, quote, similar cases). Combined with the explicit follow-up routing, an agent has everything needed to call and act on it.

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

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

Schema description coverage is 100%, so the schema already documents question, kind, state and answers. The description restates their role at a high level ('your user's question (and any AI answers so far)', reasons include 'kind, US state, task type') but adds no format, constraint or edge-case detail the schema lacks. Baseline 3 is appropriate.

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?

Opens with a specific verb and resource plus its operating character ('Read-only, free, deterministic') and then enumerates exactly what it returns: the MODE, the reasons, the favoured AI, top reviewers, the quote, and similar cases. An agent can distinguish it from siblings like summon_expert or trust_lookup 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?

Explicit trigger conditions ('Call it BEFORE answering a health, legal, tax, money or production-code question', plus the 'which AI should I use' phrasing) and an explicit next-step fork for each returned mode: answer → how_to_ask, shape_question/verify → summon_expert, live → summon_expert mode=live on an accepted job. Alternatives and conditions are named, not 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?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the leading 'Read-only' is largely redundant. The description does add real behavioral context beyond them, however: the data is redacted, published only by mutual agreement, and — importantly — must never be presented as advice for the user because their numbers differ.

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 safety/usage constraint and organized as corpus description then when-to-use then caveat. Dense but nearly every clause earns its place; the enumeration of 'the price paid and the reviewer's stamps' is the one marginally expendable detail.

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 search tool with no output schema the description does well on behavior and workflow, but with four undocumented parameters and no return-shape guidance it leaves an agent guessing about limit/state and result fields. Adequate, with a clear parameter 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 0% and the description documents none of the four parameters. Only 'kind' is loosely implied by the mention of health/legal/tax(≈finance)/code questions; 'limit' (max 10) and 'state' (2-letter) are left entirely to inference, so the description fails to compensate for the schema 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 ('Search it') and a precisely characterized resource: a published, redacted corpus of customer/reviewer-agreed checks containing the question, blind-judged AI answers, verdict, price and stamps. That level of detail makes it distinguishable from human-oriented siblings like search_human, trust_lookup and verify_human without needing to name them.

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 ('Search it BEFORE you answer a high-stakes health, legal, tax or code question'), a condition on results ('if similar cases ended with the reviewer correcting the best AI answer'), and a next action ('show your user the case and offer request_review'). It even names the sibling request_review as the follow-up route.

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, idempotentHint, and destructiveHint=false, so 'Read-only' is redundant. However, with no output schema, the description adds genuine value by disclosing the return shape: ranked cards, handles (human://name), human-set prices, proofs and track record.

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 purpose, then capability examples and return format. Dense but every clause carries information; no filler sentences. Slightly overloaded with parenthetical capability lists.

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 search with 88% schema coverage and no output schema, the description covers purpose, capability scope, and return format adequately. The main gap is not telling the agent how this fits relative to the many sibling human-interaction tools.

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 88%, so the schema already documents nearly every parameter including examples for has, country, language, and min_level. The description adds no filter syntax or format detail beyond that, making the baseline 3 correct.

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 ('Find verified humans an AI can hire per job') and enumerates the capability classes it covers (licensed opinions, human review, certified translation, lived-experience, local presence). This clearly separates it from siblings like call_human, ask_human, join_expert, and search_cases.

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 workflow ('Describe the task in plain language') and the hiring context, but never says when to choose this over call_human, ask_human, or summon_expert, nor any exclusions or prerequisites. Usage is inferable but not routed.

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 read-only, idempotent and non-destructive, so 'Read-only' is largely redundant. The description does add real behavioral context beyond the annotations: glosses on the statuses (created = awaiting payment, paid = offered with a 10-minute window) and the privacy/authorization behavior that customer_token unlocks the deliverable and private brief.

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 verb and resource, then the state glosses, then the token escalation and safety note. Dense but every clause carries domain 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 carries the return-value burden and does so by enumerating all possible statuses and disclosing the conditional extra payload. Nothing an agent needs to call it correctly appears to be 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%, so the baseline is 3. The description roughly restates what the schema already says about customer_token unlocking the deliverable, adding no format, sourcing, or error semantics beyond it.

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

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

States a specific verb+resource ('Check a job') and then enumerates the full state space the job can be in, so the agent knows exactly what is being inspected. It does not explicitly name or distinguish itself from siblings (call_human, deliver, request_review), but the resource 'job' 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?

Usage is only implied: the agent must infer that this is the polling/inspection counterpart to call_human, since that link lives in the schema parameter description rather than the tool description. There is no explicit when-to-use or when-not-to-use statement, though the customer_token clause hints at escalation for extra data.

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 it is a mutating (readOnlyHint=false), non-destructive, non-idempotent, open-world call. The description adds genuinely useful context beyond that: 'No money moves here; the user prepays at checkout_url', the blind-judging behavior in verify mode, and the requirement to read the policy resource once. It does not explain what a successful call returns (job identifier, checkout link timing), leaving a modest gap.

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

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

Front-loaded with a crisp thesis ('One verb for the human step'), then mode-prefixed clauses that keep the dense content scannable. It is packed and somewhat long, but almost every clause carries selection-relevant information rather than filler.

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

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

For a complex 11-parameter, three-mode tool with no output schema, the description covers mode behavior, trigger conditions, cost flow, and the accompanying policy resource — enough to route and invoke correctly. Remaining gaps are return values and guidance on choosing 'kind', which matter less than mode selection.

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 45%, so the description must carry weight — and it does for the critical ones: mode semantics per enum value, answers ('verify: AI answers to judge blind, 1–3; shape_question: optional'), situation ('shape_question: user's words; verify: the exact question'), and job_id implicitly via live mode. It adds little for the remaining params (kind, state, customer_type, ai_model/ai_vendor, agent_id), which stay schema-only.

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 ('summon') and resource (a licensed human), then decomposes the tool into its three modes (shape_question, verify, live) with a one-line definition of each. It also disambiguates from siblings by naming the equivalents ('same as request_review with answers', 'same as join_expert'), so an agent can tell exactly what this does versus ask_human, verify_human, or join_expert.

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 trigger conditions ('when the user asks for certainty, a professional, notarization-grade confidence or what should I even ask') plus autonomous triggers ('stakes are high: doses, deadlines, filings, money, contracts, or your confidence is low'). It also sequences the modes — 'answer only after that' for shape_question — and points to registry://summon-policy for the full policy.

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 safety profile (readOnly, idempotent, non-destructive), so the description's 'Read-only' opening is redundant. What it adds beyond structured fields is meaningful: the full shape of the return (level, proofs, per-job rates, disputes, refunds, timing) since no output schema exists, plus a useful negative constraint ('No stars, no narratives'). This is solid added context.

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

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

Roughly three sentences, front-loaded with the access mode and return contents. The dense enumeration of receipt metrics is justified because there is no output schema to carry it. Slightly redundant to restate 'read-only' given the annotation, but overall tight and purpose-driven.

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 burden of describing return values and does so thoroughly, which compensates well. It also clarifies the provenance of the identifier_hash key. The main gap is the absence of any routing guidance relative to trust-adjacent siblings, but for a two-parameter read lookup it is otherwise 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 description coverage is 100%, so both parameters are already documented, establishing a baseline of 3. The description's clause about the 'salted identifier hash returned from record_engagement' largely restates the schema's own note that this comes from a record_engagement result, adding little new syntax or format detail.

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+resource (look up trust numbers for a human or business) and enumerates exactly what is returned: a level 0–3, registry-verified proofs, and job receipts. This clearly separates it from routing/utility siblings like status or deliver. It stops short of naming which sibling it supersedes or overlaps with (e.g. verify_human, search_human), so it is not fully differentiating.

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 title's 'before you spend' implies a pre-transaction trust check, and the description tells the agent the two lookup keys (handle vs identifier_hash). However, there is no explicit when-to-use guidance or statement of when NOT to use it versus siblings such as verify_human or search_human. Usage 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 cover read-only/idempotent/non-destructive, and the description adds substantial unstructurable context: the 30-day expiry, registry signature, provenance ('every line traceable to a record'), provenance of unverifiable items, and the deliberate refusal to produce a global score. The opening 'Read-only.' is redundant with readOnlyHint, and it never says whether the subject human is notified or must consent, which keeps it from a 5.

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 dense but well-ordered block: safety/scope first, then the three output layers, then issuance terms. Every clause carries information (expiry, signature, traceability, no-global-score), though the em-dash-heavy, all-caps-emphasis style costs some readability.

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

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

There is no output schema, so the description correctly takes on the burden of describing the returned letter's contents and epistemics, which it does well. Gaps are failure modes and consent: it doesn't say what happens with an unknown handle, an under-specified task, or whether the human on the other side is prompted.

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% (only 'task' is documented) and there are no enums. The description does add real meaning for 'task' — it is the scoping input that determines which judgment is rendered, not a generic label — and 'owner's REPLY' hints at the handle's role, but the handle parameter remains undocumented in both schema and description.

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

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

The name/title plus description make it clear this produces a task-scoped verification letter about a human, and the three-layer breakdown (facts, judgment, reply) tells the agent exactly what the artifact is. It implicitly distinguishes itself from a global-scoring sibling via 'Never a global score; you decide, this informs' but never names trust_lookup or search_human, 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?

Usage is implied rather than stated: the task-scoping constraint ('a JUDGMENT for this task only', 'for one specific task') signals this is used when vetting a human for a concrete engagement, and 'Issued on request' implies on-demand invocation. However, with 15 siblings including trust_lookup, search_human and ask_human, there is no explicit when-to-use, when-not, or alternative named.

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