OffshoreProz Agent API

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered structurally. The description adds genuinely new context by stating the operation is irreversible and gated on specific statuses, which tells the agent the consequence of a wrong call. It does not describe what happens to dependent records or documents, leaving a small gap.

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

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

Three short sentences, front-loaded with the action, then the precondition, then the risk. Every sentence carries distinct information with no repetition of the title or schema.

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

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

For a single-parameter destructive tool with an output schema and full annotation coverage, the description supplies the two things that matter most: the status gate and irreversibility. Only the post-cancellation state of related artifacts is left unstated.

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

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

Schema coverage is 100% and the single parameter's schema description already carries the op_fm_* format and the status precondition. The description adds no format, syntax, or lookup guidance beyond what the schema states, 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?

States a specific verb and resource ('Cancel a formation') that is immediately distinguishable from siblings like create_formation or retry_formation. The scope is unambiguous and an agent can select it 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?

Gives an explicit precondition — only valid from draft or pending_owner_confirmation status — which effectively tells the agent when the tool applies. It stops short of naming alternatives (e.g. retry_formation for failed formations), so it is clear context without full routing guidance.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and non-idempotent, so the safety bar is lower, yet the description still adds real context: the token is short-lived, KYC and DocuSeal signature steps are triggered, and payment is involved. It never warns what a retry does to an in-flight formation, nor that a duplicate call may create a second filing — the one gap against a non-idempotent, destructive operation.

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 core action is front-loaded in the first five words, followed by the conditional AI-agent branch and then the two hard gates. The long parenthetical listing cost, timeline, KYC, payment, signature and the not-legal-advice notice is verbose but each item is a genuine prerequisite, so little could be cut without losing meaning.

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

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

For an 8-parameter, nested-object, destructive, open-world creation tool with an output schema, the description covers the gating conditions, owner typing and the downstream KYC/signature flow. It stops short of saying whether the call is asynchronous and that status should be tracked via offshoreproz_get_formation_status, which would close the loop for an agent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a cross-parameter rule not stated in the schema: beneficial_owner is always a human custodian even when owner_type='ai_agent', and agent_context.agent_id must accompany that mode. That coupling is the kind of meaning the schema alone leaves to inference.

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?

"Start forming a company" gives a specific verb (start/initiate) and resource (company formation), and the description immediately names the estimate/sibling flow it depends on. It is clear enough to separate from offshoreproz_estimate_cost, but never explicitly distinguishes itself from offshoreproz_retry_formation or offshoreproz_register, which also touch formation state.

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?

Strong on preconditions: it states both hard gates (estimate_token from offshoreproz_estimate_cost and user_confirmed_cost_and_process=true) and enumerates what the user must have seen before that flag may be set. It also gives a conditional branch for AI-agent formations. What is missing is negative guidance — e.g. use retry_formation to resume a failed formation rather than re-creating one.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond them: this read-only call is a gate that emits an estimate_token that a later write requires. It omits whether that token expires or how long it stays valid, which matters for a token-consuming dependency.

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 filler: the purpose comes first, then the hard ordering constraint front-loads the information an agent must act on. Nothing is repeated from the annotations or schema.

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

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

For a 2-parameter tool with full schema coverage and an output schema, the description covers purpose, ordering and the token dependency. The only loose end is token lifetime/reuse, which the output schema may or may not resolve, so this is strong but not airtight.

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 the schema already documents the jurisdiction code format and the obtain_ein cost/day impact. The description adds no parameter meaning beyond that, so the baseline of 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?

"Estimate the all-in cost for a jurisdiction" gives a specific verb (estimate) and resource (all-in cost), and the second sentence distinguishes it from every sibling by naming the formation flow it feeds. An agent can tell this apart from get_jurisdiction_requirements or list_jurisdictions 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 prerequisite is stated explicitly as a hard ordering rule (MUST be called before create_formation), which is exactly the guidance an agent needs to sequence a multi-step flow. It does not name when-not to call it or mention get_jurisdiction_requirements as a complement, so it stops short of full alternative 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful detail of what the log contains (status changes, portal syncs, webhooks, notes), but says nothing about retention, total volume, or how far back the trail goes.

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 core action, with no filler. Minor redundancy in 'audit trail / event log' and 'portal sync, webhooks' partially restating each other.

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 shape needn't be spelled out, and the description covers the resource, contents, and a use case. The remaining gap is routing guidance versus get_formation_status, which an agent must infer.

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 the description adds no meaning beyond it — formation_id is not clarified and the limit/ordering behavior (default 50, max 500, newest-first) is only in the schema. Baseline 3 applies when the schema carries the parameter burden.

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 ('Return the full audit trail / event log for a formation') and enumerates the content (status changes, portal syncs, webhooks, notes). It implicitly differs from offshoreproz_get_formation_status by promising the full log rather than a snapshot, but it never draws that line 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?

'Useful for debugging or understanding where a formation is in the pipeline' gives a use case, but there is no when-not guidance and no named alternative, even though get_formation_status is the obvious competing choice for pipeline position.

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 needs no restatement. The description adds a genuinely useful behavioral hint beyond annotations—that the response includes a 'next action'—but says nothing about whether status is live vs cached or how frequently it should be polled.

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 short sentence, front-loaded with the verb and resource, with no filler. It is efficient, though its brevity means it leaves sibling-routing information entirely absent.

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

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

The tool is simple: one fully documented required parameter, rich annotations, and an output schema that already explains the return values, so the description needn't cover returns. What is missing is the context that matters most for selection—how this differs from get_formation_events and list_formations.

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%: the single formation_id parameter is documented with its op_fm_* format and its provenance (returned by create_formation or list_formations). The description adds no meaning beyond that, so the baseline of 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 pairs a specific verb ('Get') with a specific resource ('status and next action of a formation'), so the agent knows exactly what it retrieves. It does not, however, distinguish this snapshot view from the sibling offshoreproz_get_formation_events, which an agent could easily confuse it with.

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 mention of alternatives. The agent must infer from the name alone that this is the polling/snapshot tool rather than the event-history (get_formation_events) or listing (list_formations) 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?

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 nothing behavioral beyond that — no note on whether requirements vary by entity type, how current the data is, or whether the returned field set is exhaustive. It is a restatement of purpose rather than added behavioral context.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though so terse that it leaves no room for the routing or scope context an agent would benefit from.

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 rich annotations cover safety; that lowers the burden considerably. However, for a tool whose output drives downstream formation decisions, the description says nothing about the nature or variability of the returned requirements, leaving it minimally adequate rather than 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%, and the schema parameter documents both format and example values ('WY for Wyoming, MI for Marshall Islands') plus the discovery path. The description adds no meaning beyond the schema for jurisdiction_code, 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 gives a specific verb ('Return') and resource ('the required fields to form a company in a given jurisdiction'), which is clear enough to distinguish this lookup from formation-mutating siblings like create_formation or cancel_formation. It does not explicitly name any sibling, so it falls short of full differentiation, but the purpose is unambiguous.

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

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

Usage is only implied: an agent can infer this is a pre-formation planning lookup. The only explicit routing hint ('Use offshoreproz_list_jurisdictions to discover available codes') lives in the input schema, not in the description. No when-not conditions or alternative tools are stated in the description itself.

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. The description adds no behavioral context beyond that – no ordering, pagination, or emptiness behavior – but it does not contradict anything either.

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 short sentence with the resource and scope front-loaded and zero wasted words. Nothing could be trimmed without losing meaning.

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

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

For a one-parameter read-only list tool with complete schema annotations and an output schema, the description covers the essentials. Only minor gaps remain around how results are ordered or paginated, which the output schema likely addresses.

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

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

Schema coverage is 100% and the single parameter already documents the op_fm_* ID format. The phrase 'for a formation' redundantly restates the parameter's role and adds no new syntax or constraint information, 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 ('List') and resource ('documents') and scopes it to 'a formation', so the agent knows exactly what is returned. It is clearly distinct from siblings like get_formation_status or list_formations, though it does not name 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?

Usage is only implied: the agent can infer it should call this when it needs the document set for a known formation. There is no explicit when-to-use condition, no mention of prerequisites (e.g. formation must exist), and no comparison against sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the meaningful detail that results are scoped to the authenticated API key and that each record surfaces status, jurisdiction, and next required actions, but says nothing about pagination, ordering, or empty-result behavior.

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 the scope statement, with no filler. The second sentence partly restates what the output schema already conveys about returned fields, which costs it a point but does not make the text wasteful.

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

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

With an output schema, rich annotations, and 100% parameter coverage, the description only needs to establish scope and purpose, which it does. Missing pagination and ordering hints are minor given how much the structured fields already carry.

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 limit, status, and jurisdiction are already fully documented in the schema, including the status enum values and jurisdiction codes. The description adds no filtering guidance 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?

States a specific verb and resource ('List all formations') plus the scoping constraint ('for the authenticated API key'), which an agent can distinguish from the singular offshoreproz_get_formation_status. It stops short of naming the sibling tools explicitly, so it is clear but not maximally differentiating.

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

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

Usage is only implied: the word 'all' suggests a broad enumeration versus the single-formation status/events tools, but the description never states when to prefer this over offshoreproz_get_formation_status or offshoreproz_list_documents, nor any prerequisite or pagination 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 openWorldHint false, so the safety profile is covered without the description. The description adds useful context beyond that: 'No sensitive data' signals it is safe to call without handling PII, and 'Call this first' conveys ordering. It says nothing about result size, pagination, or whether the pricing is indicative, which would be genuinely additive.

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 core action and scope, followed by a safety note and a sequencing instruction. Nothing is redundant and nothing could be cut without losing 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?

The tool is simple, has an output schema to explain return values, and full schema coverage for its single param, so most burden is lifted elsewhere. The description covers purpose, safety and ordering; the only gap is clarifying how the listing differs from the per-jurisdiction requirements tool in the same family.

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 one optional parameter and 100% schema description coverage, the schema fully documents include_coming_soon and its default. The description adds no further meaning about that parameter, so the baseline of 3 is appropriate even though the default listing behavior is implied.

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 ('List all available company-formation jurisdictions') and adds what the result carries ('pricing and timelines'), so an agent knows exactly what it retrieves. It stops short of distinguishing itself from offshoreproz_get_jurisdiction_requirements, which an agent could plausibly confuse with this tool.

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?

'Call this first' gives explicit workflow sequencing, implying it precedes create_formation and estimate_cost. It offers no explicit when-not or named-alternative guidance, so the boundary with the sibling requirements tool is left implicit.

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, non-destructive and closed-world, so the safety profile is fully covered by structured data. The description adds the useful scoping detail that results are limited to the authenticated API key, but says nothing about pagination, ordering, or empty-result behavior beyond what the output schema conveys.

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 scope ('authenticated API key') and the returned content ('event subscriptions and recent delivery stats') both earn their 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 zero-parameter read with an output schema and rich annotations, an agent has nearly everything needed: scope is stated and the description hints at the payload contents. The only missing piece is any note on how this relates to the webhook-registration sibling.

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 no parameter semantics to explain and the baseline of 4 applies. The description correctly implies no filtering inputs are needed by framing it as a full listing for the key.

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 ('List all registered webhook endpoints') plus the scope ('for the authenticated API key'), which is more precise than the title alone. It does not name or contrast with the sibling offshoreproz_register_webhook, so an agent still has to infer the read-vs-write split from the verb.

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

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

Usage is only implied: 'list' naturally suggests a discovery/inspection step prior to registering or debugging deliveries, but the description never says when to call it versus offshoreproz_register_webhook or when not to. With zero required parameters the usage is hard to get wrong, but no explicit routing guidance is given.

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

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

Annotations already cover the safety profile (non-readonly, non-destructive, non-idempotent, closed-world). The description adds real value beyond them: no portal login is needed, the returned key is immediately usable in-session, and a test key is distinct from a production op_live_* key. It stops short of saying whether repeated calls mint additional keys or whether the test key expires.

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 outcome and the returned key prefix, then the production alternative and the ordering hint. No filler or redundant restatement of the tool name.

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 registration tool with full schema coverage and an output schema, the description covers the essential context: what is created, what prefix to expect, and the production path. Minor omissions (key lifetime, behavior on repeat calls) are tolerable given the output schema and annotations.

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 both parameters already explain their role (name as a label, email for notifications and OTP). The description adds no parameter-level meaning beyond the schema, so the baseline of 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 ('Create a free test API key') and immediately names the artifact returned (op_test_*). It is trivially distinguishable from siblings like register_webhook or create_formation, which act on different resources.

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

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

Gives an explicit trigger ('Call this first if you have no API key yet') and routes the production case elsewhere ('complete email OTP verification via the portal'), so the agent knows both when to call it and when not to.

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

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

Annotations already declare the write/non-idempotent/open-world profile, but the description adds genuinely new behavioral context: the call returns a whsec_* signing secret that must be stored to verify payloads. It does not address what happens on duplicate registration of the same URL or whether the endpoint is verified before activation, which matters given idempotentHint=false.

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

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

Three tight sentences, front-loaded with the action and event scope, then the important return-value caveat, then the wildcard shortcut. No filler and no repetition of schema text beyond what is needed.

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, yet the description still flags the signing secret — a genuinely useful addition for a write tool. The main remaining gap is duplicate-registration behavior, which the non-idempotent annotation hints at but the description never confirms.

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

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

Schema coverage is 100%, so the schema already documents url, events, and description thoroughly; the baseline of 3 applies. The description adds only a little beyond that by repeating the wildcard behavior and naming one additional event type (formation.created) not spelled out in the schema.

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

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

The description gives a specific verb and resource ('Register a webhook URL') plus the concrete event families it delivers (formation.created, formation.status_changed, formation.complete), so the agent knows exactly what the tool does. It does not explicitly contrast itself with offshoreproz_list_webhooks or any cleanup sibling, so sibling differentiation is left to the verb 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?

Usage is implied by 'to receive real-time formation events,' and the note about '*' covers one subscription choice. However, there is no guidance on when to prefer webhooks over polling via offshoreproz_get_formation_events, no prerequisites, and no when-not-to-use case.

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, closed-world operation. The description adds the key side effect that the previous link is immediately invalidated, which an agent needs to know before calling. It does not restate idempotency or repeat-call behavior, leaving that to the annotations.

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

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

Two short sentences with no filler; the purpose leads and the destructive side effect follows immediately.

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, annotations, and a fully documented single parameter, the description supplies what is missing: the trigger condition and the invalidation consequence. Nothing essential to correct invocation 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 coverage is 100% and the single formation_id parameter already documents the op_fm_* format and the invalidation side effect. The description adds nothing about parameters beyond the schema, so the baseline of 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 names a specific verb and resource (reissue an action link) and scopes it to the current formation step and to expired or lost links. No sibling tool overlaps with this operation, so differentiation is implicit 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?

The trigger condition is explicit: use when the action link has expired or been lost. There are no named exclusions or alternatives, but no sibling performs an equivalent reissue operation, so the missing exclusion costs little.

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=false, destructiveHint=false and idempotentHint=false; the description's real added value is the state transition to pending_owner_confirmation, which explains the effect of the write. It does not say what happens when the formation is in the wrong status (error vs no-op), nor what authorization the caller needs.

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, front-loaded with the action and precondition, then the resulting state. No filler, no repetition.

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 single-parameter mutation with annotations and an output schema, the description covers both the entry condition and the resulting state, which is most of what an agent needs. The missing piece is failure behavior when the formation is not in an eligible status.

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

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

Schema description coverage is 100% and the single parameter already documents the op_fm_* format and the required status constraint. The description only restates the status condition, adding no syntax or format meaning beyond the schema, 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 gives a specific verb and resource ('Retry a formation'), plus the qualifying statuses, so it is distinguishable from siblings such as cancel_formation or reissue_action_link. It stops short of explicitly naming which sibling to use instead when the formation is in some other state.

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

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

It states the exact condition under which the tool applies ('in failed or action_required status'), which is real when-to-use guidance. It offers no exclusions or explicit alternative routing (e.g., reissue_action_link for other stuck flows), 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.