HumanFn

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

Annotations declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true), and the description adds substantive consequences beyond them: at maturity discovery nothing is charged, no attorney engagement is created, fulfillment isn't guaranteed, and a user-facing message is returned. That is exactly the kind of side-effect 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-loads the core action and the hard precondition before the negative constraints, and every sentence carries a rule. Slightly long and a few clauses restate the schema's verbatim/price requirements, but there is little true waste for a high-risk consent-recording 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 non-idempotent-looking write that records user consent, the description covers trigger conditions, anti-patterns, the alternate UI path, the financial/legal meaning at maturity discovery, and that the result contains a user message. No output schema exists, so nothing else is required.

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 defines offer_id format, accepted_price_usd matching the offer, and verbatim user_confirmation. The description only reinforces ('Pass their words verbatim', 'at its exact price') without adding new syntax or constraints, so the baseline 3 applies.

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

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

Specific verb ('Records') + resource ('USER's explicit acceptance of a HumanFn offer') with the offering sibling named (check_saas_legal_review). An agent can distinguish this from confirm_execution or offer_card_event 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?

Explicit preconditions ('Call ONLY after you showed the user the offer — name, scope, deliverable, price, turnaround, early-access status — and they clearly said yes') plus explicit exclusions ('Never call it on your own initiative, to reserve, or because you recommended it') and the alternative path (offer card button).

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-destructive, non-idempotent, open-world mutation, so the safety bar is lowered. The description adds genuine context beyond that: it routes the answer to HumanFn's reviewer and moves the request back into review for a quote, disclosing the state transition. It does not mention auth requirements, though the schema documents the access_token.

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

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

Two sentences with zero waste; the trigger condition is front-loaded followed by the effect, which is the right order for an agent deciding whether to invoke.

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

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

For a 3-parameter state-transition tool with full schema coverage and no output schema, the description covers the precondition and the resulting state change well. Nothing essential is missing, though error handling for an out-of-phase request is unspecified.

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 request_id, access_token, and answer are all documented in the schema itself; baseline 3 applies. The description adds no syntax, format, or constraint detail beyond what the schema already provides.

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

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

States a specific verb (sends the answer) and resource (HumanFn's clarifying question / the request), plus the effect of moving the request back to review. It is clear on its own, but does not explicitly distinguish itself from siblings like request_execution or get_request, which is why it falls 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?

"Use when a request is in phase needs_clarification" gives an explicit, actionable prerequisite that an agent can check before calling. No alternative tools or when-not-to-use conditions are named, so it stops short of 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 already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, but the description adds real consequence detail: no charge before payment, human review after payment, refunds governed by the quote's policy. It omits any note on repeated-call behavior, which annotations cover.

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

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

Three tight clauses, front-loaded with the pre-payment case, and the return value is noted in a final short sentence. No filler.

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

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

For a two-parameter mutation with no output schema, the description covers the main behavioral questions and states what is returned (the resulting phase). Minor gaps remain around what the phase values are, but the core is complete.

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

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

Schema description coverage is 100%, so request_id and access_token are fully documented in the schema. The description adds no format or semantic detail beyond that, so baseline 3 applies.

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

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

States a specific verb and resource ("withdraws the request" / "files a cancellation request") and describes the two phase-dependent modes of operation. An agent can distinguish this from siblings like get_request or request_execution without opening either schema.

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

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

Gives clear conditional usage: use before payment for a clean withdrawal, after payment to file a reviewed cancellation. It does not explicitly name an alternative tool or state when not to use it, so it falls short of a 5.

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

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

Annotations already cover readOnly/idempotent/non-destructive/closed-world, yet the description adds substantive context beyond them: it charges nothing, contacts no attorney, creates no engagement, and document text is never sent (input is facts only). It also clarifies the output is an assessment/offer and not a legal opinion that only the user can accept. This is meaningful disclosure an annotation can't convey.

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?

Well structured and front-loaded: purpose first, then labeled 'Call it when' / 'Don't call it for' blocks, then read-only and return notes. It is on the long side — the six-item trigger list has some overlap (payments, personal data, and finalization are closely related) — but each section is scannable and earns most of its space.

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

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

No output schema exists, and the description fully compensates by describing the return (an assessment of timeliness, which documents exist, what's missing, scope fit) plus a conditional offer, and it clarifies the acceptance model relative to accept_human_function_offer. Nothing an agent needs to call it 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 description coverage is 100%, so all 13 parameters (enums, required fields, lengths) are documented in the schema itself. The description adds only general framing ('inputs are facts about the product and documents; document text is never sent') rather than parameter-level meaning, so the 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?

States a specific verb+resource: it checks whether a situation fits HumanFn's SaaS Launch Legal Review and returns the exact offer. It draws sharp scope boundaries (only a SaaS's own ToS/Privacy Policy, attorney review of final docs), letting an agent tell it apart from adjacent legal/counsel questions 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?

Provides an explicit 'Call it when:' list of six concrete triggers (final/near-final ToS or Privacy Policy generated or edited, pre-launch, user asking if AI legal pages are safe, payments starting, personal data collected, otherwise shipping on a generic caveat) and a matching 'Don't call it for:' exclusion list. Nothing about when to invoke vs. skip is left 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?

Annotations already declare idempotentHint and destructiveHint, but the description adds real context beyond them: it says the call never charges by itself, is safe to call again, returns phase payment_required, and that the payment_url becomes invalid after a re-quote. That last point materially explains the practical consequence behind destructiveHint.

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

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

Front-loaded with the action and result, then the precondition, then the caveats. The parenthetical listing quote contents ('full price in USD, deadline, scope, evidence, cancellation policy') is slightly list-heavy but each sentence carries a distinct obligation or warning.

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 compensates by naming the returned phase and payment_url, and by explaining the human-payment step and link expiration. For a payment-flow tool with only three required params, nothing an agent needs in order to invoke and interpret it is missing.

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

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

Schema description coverage is 100% and all three parameters carry patterns and descriptions, so the schema does the heavy lifting. The description adds no format or origin detail for quote_id, request_id, or access_token beyond what the schema already states, leaving this 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?

States a specific verb and resource ('Confirms an on-site task quote the human approved') and names the concrete output ('returns the link where they pay'). It is clearly distinguishable from siblings like request_execution and cancel_execution because it names the approval precondition and the payment handoff.

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 precondition ('Use only after the human has seen and approved the quote') and a when-not clarification ('This is NOT a confirmation: the job is confirmed only after payment'). It does not explicitly name the sibling to use instead when approval has not happened, so it stops just short of a 5.

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

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

Beyond the annotations, it discloses real behavioral traits: results are bounded fixed-scope/fixed-price outcomes rather than freelancers, and on a miss 'the need is recorded as demand signal and nothing is purchased' — telling the agent no side-effect purchase occurs. This is meaningful context that the readOnlyHint=false annotation alone does not convey.

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 compact sentences, front-loaded with the usage trigger before the mechanics. Dense but every clause carries information; minor nesting of clauses slightly reduces scanability.

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 6-param lookup with no output schema, it covers what comes back (matching Human Functions plus the quoting tool) and the failure path (demand-signal recording, no purchase). Return-value detail is thin, but the essentials for calling it correctly are present.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters with examples. The description adds only the framing 'Describe the outcome you need,' which maps loosely to the objective field but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

The description states a specific verb (find) and resource (qualified human outcome / Human Function) and immediately clarifies what a Human Function is: 'bounded outcomes with fixed scope and price, not freelancers.' It also names its downstream sibling ('the tool to quote one'), so an agent can place it in the workflow 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?

The opening clause gives an explicit trigger condition — use when a step 'should be completed or verified by a qualified human professional' — with concrete examples (attorney review, sign-off, physical presence). It lacks an explicit exclusion vs. siblings like request_execution or check_saas_legal_review, but the trigger context is unambiguous.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false), so the bar is lower. The description still adds real value beyond them: 'unknown phases mean pending' resolves ambiguity in the return payload, and next_poll_after_seconds establishes a minimum re-poll interval that prevents hammering the API.

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

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

One sentence, front-loaded with the return-shape summary then the detail, with zero filler. The dense phase enumeration and return fields are all load-bearing for an agent parsing the response.

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 thoroughly — every phase value, the quote contents, job status, result, and poll interval are named. Combined with a fully documented 2-param schema, an agent has everything needed to call and interpret 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 request_id and access_token are already fully documented with patterns and provenance. The description adds nothing about parameter meaning or format; baseline 3 applies when the schema does all the work.

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 ('Returns the current state of an HumanFn request') and enumerates exactly what the payload contains (phase, quote, job status, result, poll interval). It does not, however, explicitly distinguish itself from siblings like confirm_execution or accept_human_function_offer, so an agent must infer the boundary from context.

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 mention of next_poll_after_seconds signals this is a polling tool, and the phase vocabulary hints at state-machine steps. But there is no explicit 'use this when X, use sibling Y when Z' guidance or precondition statement.

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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds the critical non-structural fact that only the UI invokes this, not the agent. It does not state what happens on duplicate events or errors, but idempotency is already declared in 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?

Two short sentences, front-loaded with scope and ending on the strongest constraint ('Never call it yourself'). Nothing redundant or padded.

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

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

With no output schema needed (it is a fire-and-forget event recorder), a fully documented schema, and clear annotations, the description supplies what an agent needs. It could say more about error or duplicate-event behavior for a caller, but for an agent that should never call it, that gap is minor.

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%, and every parameter (event enum, offer_id, card_token, contact_email) is fully described in the schema with patterns and provenance. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

The description states a specific verb and resource: recording an offer card 'shown' or 'accepted' event, and explicitly scopes it to HumanFn's offer card UI. It distinguishes itself cleanly from siblings such as accept_human_function_offer by declaring that the UI, not the agent, is the caller.

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 unambiguous when-not rule ('Never call it yourself') plus the only valid caller ('Used only by HumanFn's offer card UI'). An agent reading this knows immediately to route accept actions through accept_human_function_offer instead of this tool.

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

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true, openWorldHint=true) by disclosing the quote-only/no-charge model, human review and later approval/payment, regional coverage and decline behavior, prohibited categories, and the returned request_id + access_token required for later calls. This is exactly the behavioral context an agent needs before invoking.

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

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

Purpose is front-loaded and the sentence earns its detail, but the long single-sentence job-type enumeration and the duplicated Phoenix-metro statement (also in the address field) add bulk. Efficient overall, slightly over-packed.

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 fills the gap by explaining what is returned (request_id and access_token) and how later calls must use it. Combined with coverage of pricing model, geography, and exclusions, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so all nine parameters are already documented in the schema; the description mainly restates geography already present in the address field and adds the access-token follow-up requirement. Baseline 3 is appropriate when the schema carries 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?

States a specific verb and resource ('requests execution of an on-site task') and immediately scopes it as the physical real-world step an agent or browser cannot perform. The rich enumeration of jobs makes the tool's remit unmistakable and distinguishes it from pure digital siblings like find_human_function or get_request.

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 strong when-to-use context ('use when a task needs a human to be physically present') plus explicit when-not exclusions (illegal, weapons, drugs, medical, childcare, licensed/dangerous work) and geographic limits (Phoenix fully supported, US best effort, non-US declined). It does not name a sibling alternative to use instead, which is the only gap.

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