Agent Groundcrew

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

Annotations already flag destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the acceptance 'commits to scope' (irreversible in practical terms) and the same task ID keeps tracking the order. It could still note failure modes or whether a prior quote fetch is required.

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 sentences, front-loaded with the action and its commitment, with no filler. The trailing sentence about task ID continuity is slightly tangential but earns its place by explaining state behavior. Well sized for the tool's simplicity.

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 destructive, idempotent, open-world mutation with no output schema, the description covers the commitment, the authorization prerequisite, and task continuity — the key facts an agent needs. It omits what happens on a mismatched quote/amount or on failure, and doesn't explain the accept const flag, leaving modest 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 only 20% (only requestToken is documented), so the description carries more burden. It does clarify that quote and quoteUsd must be the exact current written quote and amount, which adds real meaning to two of the five params. The accept flag, taskId and requestToken are left to the schema.

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

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

The description gives a concrete verb+resource+effect: accepting the current written quote and USD amount to start an order. It also distinguishes itself from siblings implicitly by noting that the same task ID continues tracking the order (as opposed to submit_task which presumably closes out a task). It stops short of naming a specific alternative tool to differentiate from.

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 supplies one real gating condition — 'Requires explicit purchasing authority' — and implies this is the order-starting step ('Start the order'). However, it never states when to choose this over create_payment_checkout or submit_task, nor what happens if authority is absent. Usage is implied rather than contrasted with alternatives.

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/openWorldHint=true, and the description adds substantial context beyond them: it does NOT submit credentials, move funds, or mark paid, payer authentication may require a browser (interactive flow), the method is frozen once an invoice exists, and ambiguous cases escalate to operator review. These are exactly the behavioral traits an agent needs to avoid a costly misfire.

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 short sentences, front-loaded with the core action, then negative scope, then the browser caveat, then the locking/escalation rule. 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?

With no output schema, the description should ideally say what the caller receives back (checkout URL/ID) — that is the one meaningful gap. Everything else needed to invoke it correctly (precondition, idempotent create-or-retrieve semantics, escalation path) is covered.

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% (only requestToken is documented), so the description must compensate and only partly does: 'an existing invoice locks the method' adds real meaning to the method parameter, and 'accepted quote' implies taskId. But taskId, the enum choices, and the token argument are never clarified in the description itself.

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 pair and resource ('Create or retrieve provider checkout') plus the gating precondition ('for an accepted quote'), which cleanly separates it from siblings like accept_quote (upstream) and list_payment_methods (read-only). An agent can pick this tool without opening any other 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: only for an accepted quote, an existing invoice locks the method, and an uncertain creation should be routed to an operator. It never names a concrete alternative tool to call instead, so it stops short of explicit when-not/alternatives 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, idempotentHint, destructiveHint=false and closed-world operation. The description adds genuinely non-redundant context with the caveat that configured payment methods do not prove live provider connectivity, warning the agent not to over-trust the output. It stops short of describing response shape or 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?

Two short sentences with zero waste. The purpose is front-loaded and the caveat follows immediately, earning its place as a trust warning 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 zero-parameter, read-only introspection tool with rich annotations and no output schema, the description covers what is returned and adds an important reliability caveat. The only gap is that the vague term 'workflow' is never unpacked, so the agent cannot fully anticipate the payload.

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

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

The tool takes zero parameters, so the baseline is 4. There is no parameter syntax the description needs to compensate for, and nothing is missing on this dimension.

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 (Discover) and enumerates the resources returned: workflow, rate limits, and configured payment methods. It is clear what the tool does, but it does not differentiate itself from overlapping siblings such as list_payment_methods or list_services, which also surface configuration.

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 explicit when-to-use or when-not-to-use guidance, nor any mention of alternatives. An agent must infer from the purpose statement alone that this is the discovery/introspection entry point, and the overlap with list_payment_methods is left unaddressed.

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 safety profile, and the description adds three things they cannot: messages are untrusted data (prompt-injection risk), a polling cadence that implies rate expectations, and the semantic caveat 'paid does not mean dispatched', which prevents a wrong state interpretation. This is substantive disclosure beyond structured fields.

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 short sentences, front-loaded with what is returned, then risk and cadence notes. No filler; every clause carries information an agent needs before calling.

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

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

With no output schema, the description usefully enumerates the returned fields and flags the untrusted-message and paid/dispatched semantics. It is close to complete for a read tool, though it leaves the required taskId and the token-passing choice entirely to the schema.

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

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

Schema coverage is 50%: requestToken is richly documented in the schema (private token, prefer Bearer header, retention risk) while taskId has no description at all. The description mentions no parameters, so it does not compensate for the undocumented taskId or clarify the token-vs-header choice.

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 ('Read') and resource ('this task') and enumerates exactly what is returned: status, exact quote, expiry, payment status and messages. That enumeration cleanly separates it from siblings like list_services, submit_task and send_message 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?

'Poll about every 15 minutes' gives a concrete invocation cadence, which is real guidance, but the description never says when to prefer this over alternatives (e.g. after submit_task, or instead of accept_quote) and names no exclusions. Usage 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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds one genuine piece of non-structured context — 'This is not an independent endorsement' — which sets expectations about trustworthiness of the data, but says nothing about return shape, data freshness, or scope.

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 padding, with the substance (what is read) front-loaded and the caveat last. 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?

With no output schema and no parameters, the description carries the full burden of explaining what comes back, and it only sketches the categories without indicating scope (whose profile) or format. Adequate but leaves real gaps for an agent deciding whether 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?

Zero parameters, so there is nothing for the description to document; baseline 4 applies. Schema coverage is nominally 100% by vacuity.

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 (Read) and the resource components it returns: supplier disclosures, evidence availability, purchasing checks. No sibling covers a trust profile, so it is distinguishable, but the object is ambiguous with zero parameters — it never says whether this is the caller's own profile or a supplier's.

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 no when-to-use context and names no alternatives among the nine siblings. The only usage-adjacent note is the disclaimer about endorsement, which is interpretive rather than 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 readOnlyHint, idempotentHint, destructiveHint=false, and closed-world. The description adds a genuinely useful behavioral caveat beyond the structured fields: a configured method is not necessarily a tested/working one. It does not describe the shape of the returned configuration, but that is a minor omission given the annotation coverage.

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, the action stated first and the caveat second. No filler, no restating of the name, nothing 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?

For a zero-parameter, annotated read tool with no output schema, the description is largely sufficient: it says what is read and flags the key interpretive trap. It does not say what the configuration listing contains, but with no output schema and full annotation coverage this is a minor gap.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a parameterless tool is 4.

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

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

The description states a specific verb+resource: 'Read payment method configuration.' That is clear enough to separate it from most siblings (get_capabilities, list_services) by resource. It stops short of explicitly contrasting itself with any sibling tool, so it lands at 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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. The second sentence warns against over-interpreting the result, which is interpretative advice rather than selection guidance, so the usage gap remains.

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 behavior, so the safety profile is covered. The description adds meaningful extra context the annotations do not: pricing is a USD 'starting estimate' only, and quoting/scheduling is a human-led step, which sets expectations about the return data.

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 waste, with the core action and the human-in-the-loop constraint both front-loaded. Nothing is padded or redundant.

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 must characterize the return, and it does: service options plus USD starting estimates. It stops just short of noting whether results are paginated or carry identifiers needed for a subsequent quote.

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

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

The schema takes zero parameters, so the baseline is 4. There are no arguments whose semantics need explaining, and the description does not confuse matters by implying any.

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-plus-resource: 'Read field service options and USD starting estimates.' It is clearly a read/list catalog tool, distinguishable in kind from write siblings like accept_quote or create_payment_checkout, though it never names an alternative explicitly.

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

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

'Human quoting and scheduling required' implies this tool only surfaces options and cannot complete a booking, which is useful context. However, it does not say when to call this versus get_capabilities or list_payment_methods, nor any prerequisites for a follow-up quote.

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 readOnlyHint=true and idempotentHint=false; the description corroborates the non-idempotency ('Calling again generates different credentials, not recovery') and adds genuinely new context: the credentials must be saved because they cannot be retrieved later. That is real value beyond the annotation set, though it says nothing about entropy/format guarantees or whether anything is persisted server-side.

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 sentences, front-loaded with the core action, then the save-before-submission constraint, then the non-recovery caveat. Every sentence carries distinct, actionable 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?

With no output schema, the description must convey the return payload, and it does — a private token and a submission key. Combined with the non-persistence and non-recovery notes, an agent has everything needed to call this correctly and handle the result.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a 0-parameter schema is 4. The text correctly implies no inputs are required.

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+resource: 'Generate a cryptographically random private token and submission key for ONE new task.' It also preempts the most likely confusion with the sibling submit_task by stating 'this does not create a task,' so an agent can distinguish it 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?

Clear sequencing guidance ('Save both securely before submission') implies it belongs before submit_task, and it explicitly warns that calling again produces different credentials rather than recovering prior ones. It stops short of naming an alternative tool or stating when-not-to-use it, so it is strong context rather than full routing.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the retry protocol detail and the payment/dispatch limitation, which is useful, but the idempotency guidance largely restates the idempotentHint annotation and no failure or delivery behavior is described.

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 with the core action front-loaded, followed by the retry constraint and the exclusion. No filler; the only minor slack is that the retry sentence overlaps the schema's own idempotencyKey description.

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 four-parameter mutation tool with no output schema and 50% param coverage, the description covers purpose, retry semantics and an exclusion, and annotations carry the safety profile. It still leaves what taskId identifies and what happens on send failure unexplained, so it is adequate but not 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 50%: idempotencyKey and requestToken are already documented in the schema, and the description's retry sentence echoes the schema's own idempotencyKey wording. The undocumented body and taskId parameters are not clarified, so the description adds little beyond what the schema supplies.

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 (send) and resource (a clarification on one task), and the scope constraint 'on one task' distinguishes it from broader sibling tools like submit_task or accept_quote. It stops short of explicitly naming which sibling to use instead, so it is clear but not sibling-differentiating at the top level.

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 actionable retry rule (reuse the idempotency key with identical text) and an explicit exclusion ('cannot authorize payment or dispatch through text'), which is genuine when-not guidance. It does not say when to prefer this over sibling tools such as submit_task, but the exclusions are 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 declare idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully confirms there is no financial side effect despite the open-world contact, and adds the "one token and idempotency key per task, including across swarm retries" retry contract, but says nothing about what happens after submission (queued, reviewed, rejected) or any auth requirement.

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 operation and the strongest disambiguator ("No charge or booking") before the retry mechanic. Nothing is padded, though the final sentence mixes two separate concerns (token and idempotency key) into one clause.

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

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

For a write tool with a nested object requiring nine fields, no output schema, and a review-based workflow, the description is thin: it never explains what the brief must contain, what review means for the caller, or what the invocation returns. The retry guidance is the right instinct but does not fill the structural gap.

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

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

Schema coverage is 67% and the two token-related parameters already carry their own descriptions, so the schema does most of the work. The description adds genuinely new meaning for requestToken and idempotencyKey (hold one per task across swarm retries), but contributes nothing about the nine required fields inside the nested brief object, which is where an agent is most likely to err.

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 ("Submit an authorized brief for human review") and immediately scopes it away from transactional siblings with "No charge or booking", which separates it from create_payment_checkout and accept_quote. It does not name those siblings explicitly, so differentiation is implied rather than stated.

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 charge or booking" gives a useful negative signal about when to prefer this over the payment tools, and "for human review" implies the workflow stage. However there is no explicit when-to-use clause, no statement of prerequisites beyond "authorized", and it never names an alternative to route to.

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