flixconomy.ai: humans and Ari for agents

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is not required to restate them. It does add one genuinely useful behavioral fact not in the annotations: the tool is unreleased ('Coming soon'). Beyond that it says nothing about latency, cost, or how the coaching interaction proceeds.

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

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

Two short sentences with the availability caveat front-loaded, so nothing is buried and no filler is present. The brevity, however, reflects under-specification rather than disciplined economy.

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?

An output schema exists, so return values need not be described, but the description still omits what the tool actually does when invoked and what the agent should supply as a 'situation'. For a tool the agent is meant to call with a meaningful free-text input, the definition is too thin to act on.

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 single parameter ('situation') has no title-level explanation in the schema. The description never mentions what a 'situation' should contain, its format, or length, so it fails to compensate for the documentation 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?

The description names a resource ('coaching by Agent: Ari') and a rough purpose ('helps your agent with a hard decision'), but it is largely marketing framing rather than a stated operation. 'Coming soon' dominates, leaving the actual mechanic (advice request? conversation? single-shot?) unclear, so an agent cannot confidently distinguish it from siblings like ask_a_human or rent_a_human on function alone.

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?

'Helps your agent with a hard decision' implies a trigger condition, and 'Coming soon' implies it should not be invoked yet, which is a form of usage constraint. However, no alternative is named and no explicit when/when-not guidance is given, so the routing signal is inferred rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds almost nothing behavioral — it doesn't say whether this opens a ticket, returns an answer synchronously, or has latency; 'Coming soon' hints at availability but stops short of clarifying what happens when invoked.

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?

Only two short sentences with no filler, which is good. But the front-loaded slot is spent on an availability caveat ('Coming soon') rather than the tool's purpose, so the most decision-relevant information arrives second.

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?

An output schema exists so return values needn't be explained, and annotations cover safety, but for a tool whose availability is explicitly in doubt and whose single parameter is undocumented in both schema and description, an agent lacks enough to decide whether and how to call 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?

One parameter ('question') exists with 0% schema description coverage and no required flag, so the description must compensate. It only gestures at the parameter ('hand a support question') without stating expected format, length, or whether an empty default string is meaningful, leaving the schema's gaps unfilled.

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 does state what the tool does — escalate a support question the agent can't resolve to 'Ari' — but the leading 'Coming soon' muddies whether it is callable at all. It never distinguishes itself from near-identical siblings like ask_a_human or get_human_answer, so an agent cannot confidently route between 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?

'Hand a support question your agent can't settle to Ari' implies a trigger condition (unresolvable questions), which is useful context. However, it names no alternatives or exclusions, which is a serious gap given three sibling escalation tools exist and no guidance selects among them.

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

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

Annotations only declare the generic write/openWorld/idempotent profile; the description goes far beyond by disclosing the credit debit, tiered pricing by deadline, and the expiry/refund behaviour ('full price returns to your credit'). It also states the immediate return payload (id, price, due time), which is exactly the kind of operational context 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 return contract, then uses a clean per-parameter structure. It is dense but nearly every line carries actionable information; the pricing tier list is verbose but justified because cost is a decision input for the caller.

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?

An output schema exists so return values need not be re-explained, yet the description still summarises the immediate payload usefully. The only real gap is the undocumented max_wait_minutes parameter, so completeness is high but not total.

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

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

With 0% schema coverage the description must compensate, and it documents question, options (2-10 choices plus comment), context, api_key, and answer_within_minutes with its 15-10080 range and pricing. However max_wait_minutes is left entirely undocumented, and the description labels answer_within_minutes as required while the schema marks only question as required, a minor mismatch.

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 ('Ask a real human a short question') and immediately distinguishes itself from its follow-up sibling by naming get_human_answer for collecting the result. An agent can tell what this does and how it differs from get_human_answer 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 clear context for use, describing the kinds of questions suited to it (taste, judgement, approval, sanity check) and stating the answer must be collectable via get_human_answer. It does not explicitly contrast with siblings like rent_a_human, so it stops short of the full when-not 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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the mutation and safety profile is covered. The description adds real value beyond that: the refund condition and the acceptance-time boundary, which an agent needs to reason about consequences. It does not explain post-acceptance behavior or error cases.

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, zero filler, with the action front-loaded and the refund consequence immediately following. Nothing is wasted.

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

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

An output schema exists so return values need not be explained, and annotations carry the destroy/idempotency profile. Still, for a cancellation tool the description omits what 'id' refers to, whether cancellation after acceptance is possible, and what happens to the task afterward — meaningful 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 0% for two parameters, and the description adds no meaning: it never clarifies that 'id' is the task identifier nor what 'api_key' is for. With low coverage, the description should compensate, and it does not.

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

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

States a specific verb+resource ('Cancel a task from rent_a_human'), which is clearly distinct from siblings like get_task, message_task_human, and rent_a_human. It does not explicitly name an alternative sibling, but the operation and its domain are 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?

The description implies usage timing via the refund rule ('Before a human accepts it'), which tells the agent this is for pre-acceptance tasks. However, it never states what to do after acceptance, whether cancellation is still possible, or which sibling to use instead, leaving the boundary 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 give basic write/open-world signals, but the description adds critical behavior: the return values (account key and top-up link), the secret-handling requirement for the key, what the key can and cannot do, external Stripe payment from 10 EUR, and the human's email role. This is rich context beyond annotations.

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

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

Front-loaded with the core action and key constraint ('No key needed'). Every sentence is informative: returns, payment link, email usage, next call. 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?

Given a parameterless create tool with an output schema and partial annotations, the description covers all necessary workflow details: account creation, key handling, payment setup, and the follow-up call to create_api_key. Nothing essential is missing.

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

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

There are zero parameters, so the schema cannot document any. The baseline for a parameterless tool is 4; the description correctly adds no parameter semantics because none exist.

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 (Create) and resource (flixconomy.ai account), specifies the audience ('for yourself'), and distinguishes the next step by naming create_api_key. An agent can tell what this tool does without inspecting 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 clear context for when to use it ('No key needed') and what to do next ('After the payment, call create_api_key'). However, it does not explicitly exclude use when an account already exists (e.g., 'if you already have an account, use get_account'), leaving a minor gap.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write, so the safety profile is covered. The description adds two behavioral facts beyond the annotations: the key is 'shown once' (critical — the agent must capture it immediately) and the account must have credit.

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, front-loaded sentences with no filler; the create action leads and the caveats follow. The inline name example is compact 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?

An output schema exists, so return values need not be described. The description covers the write action, the credit prerequisite and the one-time display, leaving only account_key undocumented — a small but real gap for a 2-parameter 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 must carry the load. It clarifies 'name' with a concrete example label, but the second parameter 'account_key' is left completely unexplained in both schema and description, so it only partially compensates.

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 an API key') plus the scope ('for all flixconomy.ai services'), which is more than the bare name conveys. It does not explicitly distinguish itself from the sibling delete_api_key, but the create/delete distinction 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?

The description gives a precondition ('Needs credit on the account'), which is genuine usage context, but it never states when to choose this tool over alternatives (e.g. create_account) or when not to call it. Usage is only 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context that annotations cannot express: the key keeps working for a few minutes after deletion, which sets correct expectations about propagation delay.

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, zero filler, with the core action stated first and the useful timing caveat second. Every clause 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?

An output schema exists, so return values need not be described. The definition covers the action and its delayed effect; the only material gap is the undocumented account_key parameter and the lack of any note on irreversibility beyond what the destructive annotation implies.

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% for two parameters. The description compensates for key_id by telling the agent it comes from get_account, but account_key is left completely unexplained in both schema and description. Partial compensation warrants a mid score.

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

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

The description gives a specific verb and resource ('Delete an API key of your account'), which is unambiguous and inherently distinguishable from the sibling create_api_key. An agent knows immediately what operation this performs.

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 parenthetical '(key_id from get_account)' points the agent at the sibling that supplies the required parameter, which is useful routing. However there is no explicit when-to-use/when-not guidance, e.g. no warning about deleting the key currently in use or whether a replacement key should be created first.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description goes beyond them by disclosing the authentication mechanic: the fxa_... account_key, its origin in create_account, and that it may alternatively be passed as an Authorization header. It does not say what happens when the key is omitted (the parameter defaults to an empty string).

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, and the resource inventory is front-loaded before the credential mechanics. The parenthetical about the Authorization header is compact and useful rather than padding.

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

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

With an output schema present, return values need not be detailed, and the description correctly focuses on scope and auth. The one thing missing for an agent choosing between this and get_credit is the differentiation, but nothing needed to call the tool correctly is absent.

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 burden falls on the description, and it largely delivers: it names the parameter's source tool, its fxa_... format, and an alternate transport (Authorization header). It stops short of explaining the empty-string default or the behavior of an unauthenticated call, which is the only remaining gap for 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 enumerates exactly what the account resource contains (credit, usage, API keys, payments, top-up link), which is more specific than a restated name. However, it never distinguishes itself from the sibling get_credit or explains how the two overlap, leaving the agent to guess which to call for credit data.

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

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

There is no when-to-use guidance and no exclusions; the sibling get_credit is not mentioned even though the description claims this tool also returns credit. The only routing hint is that the key originates from create_account, which is setup information rather than usage 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds two genuinely useful behavioral facts beyond that: the balance is denominated in EUR and the payload also reports consumed credit plus a top-up pointer. It stops short of richer context such as whether the api_key may be omitted or rate limits, so a 3 is appropriate.

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

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

A single front-loaded sentence with no filler; the core action comes first and the secondary details (currency, usage, top-up) follow in the same sentence. Nothing is redundant or padded.

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

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

With an output schema present, the description need not describe return values, and the rich annotations cover the safety profile, so the remaining burden is small. The one real gap is the optional/default behavior of api_key, which is left unaddressed in both description and schema.

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

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

Schema description coverage is 0% for the single api_key parameter, so the schema alone gives no semantics. The description partially compensates by tying the call to 'the account of your API key', implying the key identifies whose credit is returned, but it never explains that api_key is optional (default "") or what happens when it is omitted.

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

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

Specific verb ('Show') and resource ('the credit left on the account of your API key'), with added detail on currency (EUR) and the two companion outputs (what was used, where to top up). It is distinguishable in substance from get_account and get_price, but it never names or contrasts a sibling explicitly, which keeps it just 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?

There is no when-to-use statement, no prerequisite, and no alternative named. The agent must infer that this is the tool to call when it wants a balance check, and nothing tells it when to prefer get_account or get_price instead.

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 (which already declare readOnly/idempotent/non-destructive) by disclosing the blocking wait window (0-45s), the polling contract for open status, the refund behavior on expiry, and an authorization constraint ('only the API key that asked can read it'). These are exactly the operational traits an agent needs before calling.

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 tight paragraphs, front-loaded with the action and the wait behavior, then the status/return semantics. Every sentence carries distinct information with 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 3-parameter polling tool with an output schema, the description supplies the polling loop, the timing bound, the auth constraint, and the meaning of each status branch. Nothing needed to call or interpret the call 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 0%, so the description must carry parameter meaning and largely does: it names what 'id' refers to (a question id from ask_a_human), gives the valid range for wait_seconds (0 to 45), and implies api_key must be the key that asked the question. The api_key semantics are only implicit, 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 specific verb and resource (get status and answer for a question id) and explicitly ties it to the sibling tool ask_a_human, which is the tool that created the question. An agent can tell it apart from ask_a_human and message_task_human 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 context is explicit: use this to poll a question created by ask_a_human, and the 'status is open (call again)' clause tells the agent exactly when to re-invoke. It does not name any competing alternative for retrieving results, but the workflow routing is clear.

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

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

Annotations already cover the read-only/idempotent/non-destructive profile, but the description adds genuinely new behavior: nothing is charged, and it names the two operational modes (ask vs task). It also discloses the response keys price_eur and due_at, useful context even though an output schema exists.

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 tight sentences that front-load the value proposition and then the parameter contract; almost no filler. The telegraphic phrasing is dense but every clause carries real information.

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

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

For a 4-parameter tool with no schema descriptions, the description covers the parameter contract well and an output schema exists to explain the return payload. Remaining gaps are minor (no defaults, no error behavior), so it is nearly complete 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 0%, so the description must carry the load, and it does: it enumerates kind values ('ask'/'task'), ties answer_within_minutes to 'ask' and budget/deadline to 'task', and gives units and formats (EUR, ISO 8601). Minor gap: no mention of defaults or what happens if kind is invalid.

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 (getting a price) and adds the crucial qualifier 'nothing is charged', which separates it from the actual ask/rent siblings. It does not explicitly name ask_a_human or rent_a_human, but the pre-quote framing makes the purpose 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?

'Price before you ask' implies this is a prerequisite step for the human-facing siblings, and the two kind branches give invocation context. However, it never explicitly says when to use this versus ask_a_human/get_human_answer, so routing 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data. The description adds that the response includes status plus all messages with the human, but says nothing about auth needs for api_key, message history limits, or whether messages are paginated.

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

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

A single front-loaded sentence with no filler; the status enumeration is compact and the message payload is mentioned in the same clause. Nothing is wasted.

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

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

An output schema exists, so return-value details need not be restated, and annotations carry the safety profile. The remaining gap is parameter guidance (id format, role of api_key) for a tool that is otherwise simple enough that the description is close to sufficient.

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 never mentions either parameter. The 'id' is inferable as the task identifier from context, but the api_key parameter (with a default of empty string) is entirely undocumented in both the schema and the description, so the description does not compensate for the coverage gap.

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

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

States a specific verb+resource ('Get the status of a task') and enumerates the possible status values (open, accepted, done, cancelled, expired), which pins down what 'status' means. It also adds the messages payload. It does not name a sibling to distinguish from (e.g., get_human_answer), so 4 rather than 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?

Usage is implied: the agent can infer this is the poll-a-task tool given siblings like get_human_answer, message_task_human, and cancel_task. However, there is no explicit when-to-use, when-not-to-use, or alternative routing (e.g., 'use get_human_answer to retrieve a completed answer').

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive, open-world write. The description adds the state precondition ('works while the task is open or accepted'), which annotations do not cover. However, it stays silent on what happens outside that state (error?), whether the message is appended or replaces prior context, and whether the human is notified.

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, no filler, with the core action front-loaded and the precondition as a follow-up. Every clause carries 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?

An output schema exists, so return values need not be described. Still, for a write tool with an open-world, non-idempotent profile and zero parameter documentation, the description omits what occurs on failure or when the task is not open/accepted, leaving the agent with questions before invoking 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 0% across 3 parameters (id, api_key, message). The description names no parameter and does not clarify that 'id' is the task identifier or how message/api_key are used, so it fails to compensate for the documentation 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?

The description states a concrete verb and resource ('Send a message to the human on a task') and clarifies intent with the parenthetical 'answer their question, add details'. It is clearly distinguishable from write-side siblings like ask_a_human, but it never names or contrasts them explicitly.

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

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

'Works while the task is open or accepted' implies a valid operating window, which is genuine usage context, but there is no explicit when-to-use vs. alternatives guidance (e.g., when to message via an existing task versus using ask_a_human or get_human_answer).

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

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

Annotations only declare that this is a non-read-only, non-idempotent, open-world write; the description goes well beyond that by disclosing the fee schedule tied to deadline (20%/30%/50%), that the fee plus budget is debited from account credit, the refund conditions (cancel before acceptance, or status 'expired'), and the budget range of 10-500 EUR. These are exactly the monetary and reversibility facts an agent needs before invoking a paid, non-idempotent action.

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 first sentence front-loads purpose and return values, and the subsequent block is dense with payment, deadline, and refund facts rather than filler. The layout is a bit lumpy — fee mechanics, parameter definitions, and refund rules run together in one block — but almost 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?

For a paid, open-world task-posting tool with a 6-parameter schema, the description covers pricing, deadline floor, payment source, cancellation/expiry refunds, and the meaning of every input. An output schema exists, so the brief mention of returned values (task id, price, due time) is a bonus rather than a gap-filler, and nothing consequential 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?

With 0% schema description coverage, the description carries the burden and mostly delivers: it explains deadline format and 4-hour minimum, budget semantics and range, location meaning, title/description intent, and api_key as an alternative to the Authorization header. The one blemish is that it labels deadline '(required)' while the schema's required list contains only title, description, and budget, so the description slightly misstates the contract.

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 ('Post a paid task for a real human') and scopes it to online or on-site physical work, which is concrete enough to act on. It does not, however, distinguish itself from the sibling ask_a_human, which an agent would likely consider for a near-identical need.

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 context is implied by the constraint that the deadline must be at least 4 hours ahead and that the task is paid and immediately visible to humans, which hints at when this tool is appropriate. But there is no explicit when-to-use versus ask_a_human or get_price, and no stated exclusions, leaving the routing decision 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 confirm a non-destructive, non-readOnly, open-world write, and the description adds substantively: email triggers a confirmation link and updates only flow after confirming (double opt-in), while agent_card_url/mcp_url/webhook_url are stored as a contact and "nothing is sent yet." That is meaningful disclosure beyond the annotations, though duplicate/idempotency behavior is not addressed.

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 lead sentence front-loads purpose and the no-key fact, then parameter documentation follows in compact labeled lines. Slightly dense but each line carries information the schema lacks.

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 an output schema present, return values need not be explained, and the description covers all six parameters, authentication, and the opt-in lifecycle. Minor omissions like array/null handling for interests and idempotency keep it off a 5.

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 must carry the burden, and it largely does: email is the human's address, name is a label, the three URLs are public https contacts, and interests are enumerated (ask, rent, coaching, support, agi, human). It does not clarify that interests accepts an array or null, a minor gap.

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

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

States a specific outcome (get notified at service launch and about news) tied to named services, so the agent knows this is a subscription/notification tool. It is clearly distinct from the siblings like ask_a_human or ari_coaching, though it never explicitly contrasts itself with 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?

"No key needed" plus the double opt-in explanation tells the agent this is a no-auth, low-commitment subscription, which is real usage context. It stops short of an explicit when-to-use-vs-alternatives statement, which is acceptable here since no sibling overlaps the subscription role.

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

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

The annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description usefully adds that the tool operates through an agent-to-agent conversation rather than a simple call, plus the "Coming soon" availability caveat, but it says nothing about runtime cost, duration, or what the conversation requires of the caller.

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, and the availability caveat is front-loaded, which is good. The second sentence is a dense, list-like abstraction ("own vision, drive without an assignment, steadfastness with reasons and morality") that is flavorful but low on actionable 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?

An output schema exists so return values need not be explained, and complexity is low with one optional parameter. However, "Coming soon" leaves the critical question of whether the tool can be invoked at all unanswered, and the "about" parameter is undocumented, so an agent lacks what it needs 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 0% and the single "about" parameter is never mentioned in the description, so the caller has no idea what to supply. Unlike the zero-parameter baseline, there is an undocumented input here that neither schema nor description explains.

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 does state a verb and resource ("Test your AGI") and explains the mechanism: Ari holds a conversation with your agent and evaluates vision, drive, steadfastness and moral reasoning. But the purpose is abstract and the leading "Coming soon" muddies whether the tool is even usable, so the agent cannot cleanly tell it apart from evaluation-adjacent siblings like ari_coaching or ari_support.

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

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

There is no when-to-use, when-not-to-use, or alternative guidance. Nothing says how this differs from ari_coaching or ari_support, and "Coming soon" gives no signal about availability or prerequisites for invocation.

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