gvrn-incorporation

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

Annotations already declare non-read-only, non-destructive, non-idempotent, closed-world. The description adds real context beyond that: drafts must be bound to a verified email, partial drafts are permitted, and the call returns a draftId used by later operations. It does not warn that repeated calls create separate drafts (relevant given idempotentHint=false), which would have earned a 5.

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

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

Three short sentences with zero filler. The prerequisite token is stated first, optionality second, and the returned identifier last, which matches the order an agent needs them.

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 twelve-parameter creation tool with no output schema, the description covers the gating requirement, the partial-draft behavior, and the return value at a high level. Deeper guidance on the founder array or a draft-already-exists scenario is absent but not essential to call it 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 coverage is 100%, so all twelve parameters including the nested founder object are documented in the schema itself. The description only restates the required/optional split ('every other field is optional'), which the schema already encodes via the required array. 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 ('Creates a new incorporation request draft') plus the binding constraint (verified email). It is clearly separable from siblings update_incorporation_draft and submit_incorporation, which act on an existing draft.

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?

Names the prerequisite explicitly (a verificationToken from verify_email_otp) and points to the downstream lifecycle — later updates, submission, status checks — which implicitly routes the agent to the sibling tools. It stops short of an explicit 'use update instead if a draft already exists' exclusion.

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 provide readOnlyHint=true and destructiveHint=false, so the safe read-only behavior is established. The description adds content scope and the alternative MCP resource URI, but discloses no further behavioral traits such as response format, pagination, or authentication requirements.

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 compact, focused sentences. The primary return value is front-loaded, the content list adds concrete value, and the MCP resource note is delivered as a brief secondary detail.

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

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

For a zero-parameter, read-only retrieval tool, the description is fully sufficient. It states what is returned, summarizes the guide's contents, and notes an alternative access method; no output schema is present but the description covers expectations adequately.

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 has zero parameters and the input schema is empty, so there is nothing for the description to clarify. With no parameters, a baseline of 4 is appropriate.

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

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

States a specific verb and resource ('Returns the full GVRN incorporation workflow guide') and enumerates the content (fields, email-verification steps, review lifecycle). This clearly distinguishes it from the status, draft, and submission tools in the sibling list.

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 use when the full incorporation workflow guide is needed, but it gives no explicit when-to-use guidance and does not contrast with alternatives like get_incorporation_status or the draft/submit tools. The sibling list is not referenced within the description.

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, non-destructive, closed-world profile, so the bar is lower, and the description still adds real context: an authorization requirement (verificationToken bound to the creating email) and an access-scoping rule (visible only to that email). It does not describe rate limits or what happens on token mismatch/expiry, which would be needed for a 5.

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

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

Two tight sentences with zero filler: the return value and status flow come first, followed by the single precondition. Nothing is repeated and 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?

For a two-parameter read tool with full schema coverage and no output schema, the description is nearly sufficient, conveying both authorization and the status lifecycle. It stops short of indicating whether additional fields (timestamps, reviewer notes) accompany the status, a minor residual 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 100%, and the schema already explains that draftId comes from create_incorporation_draft and verificationToken from verify_email_otp. The description only reinforces the email-binding of the token, adding little meaning beyond the structured fields, so baseline 3 applies.

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

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

States a specific verb and resource ('Returns the current status of an incorporation request') and enumerates the status values, which sharpens what is actually returned. It does not explicitly contrast with siblings like submit_incorporation or update_incorporation_draft, so an agent must infer the distinction, keeping it below 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?

Gives a clear precondition for use: a verificationToken for the email that created the draft is required, and requests are only visible to that email. There is no explicit when-not or named alternative, so no exclusions are stated, but the usage context is unambiguous.

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

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

Annotations cover safety (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description adds material traits the annotations cannot express: a 10-minute expiry window and per-email rate limiting. It also discloses the downstream authorization chain, which is exactly the behavioral context an agent needs before triggering an outbound email.

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

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

Two sentences, zero filler, with the irreversible side effect (sending mail) and the critical constraints (10-minute expiry, rate limit) all front-loaded before any agent would need to page further.

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

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

No output schema exists, and the description implicitly describes the side effect rather than the return value — it does not say whether the call returns a confirmation, an error on rate limit, or when the code may be resent. Given the simple single-parameter shape, the flow, expiry, and throttling coverage make it nearly complete, but the response/error behavior is the one remaining 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?

Only one parameter with 100% schema description coverage, so the schema already carries the semantics ('the user's real inbox', maxLength 320). The description adds nothing about the parameter beyond 'the given email address', 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 ('Sends a 6-digit verification code to the given email address') with the exact payload format, and explicitly distinguishes itself from the sibling verify_email_otp by assigning that tool the token-exchange role.

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?

Explains the workflow position clearly: this is step one, the code is exchanged via verify_email_otp, and the resulting token 'authorizes the draft tools' — that ties it to create_incorporation_draft and update_incorporation_draft. It stops short of stating when not to call it (e.g. if a token is already valid), so it is contextual rather than exhaustive.

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 flag destructiveHint=true and idempotentHint=false, but the description goes further: it spells out exactly what is destroyed ('the draft becomes read-only'), that a review request is filed, and that the token's email becomes the request contact. That is concrete consequence-level disclosure beyond the annotation flags.

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 action and then the prerequisite and the irreversible consequence. The line 'Optional fields may be left blank' is the weakest — the schema exposes no optional parameters, so it refers obliquely to draft fields and reads as filler.

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

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

For a two-parameter, non-idempotent mutation with no output schema, the description covers prerequisite, side effects, reversibility, and return value. An agent has everything needed to decide to call it and to warn about the consequences.

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 both parameters are already documented with their upstream sources. The description adds one real fact — the verification token's email becomes the contact for the request — but nothing about draftId semantics, so the baseline of 3 holds.

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 ('Submits a draft for review by the GVRN team') plus the return value ('returns the request status'). That cleanly separates it from update_incorporation_draft and get_incorporation_status among the siblings.

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?

Makes the precondition explicit: a verificationToken is required, and the schema ties it to verify_email_otp and the draft to create_incorporation_draft, so the call chain is inferable. It stops short of naming alternatives or saying when NOT to submit (e.g. draft not ready), so it is not a full 5.

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

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

Goes well beyond the annotations: it discloses patch semantics (unspecified fields are preserved), the non-obvious array replacement rule, the auth precondition (token bound to the draft's email), and a hard failure mode after submission. None of that is recoverable from readOnlyHint/idempotentHint/destructiveHint alone, and the patch behavior is consistent with idempotentHint=true.

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, no redundancy. The mutation semantics come first, then the auth precondition, then the failure condition — the order an agent needs to decide and then call.

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 13-parameter mutation with full schema coverage, the description covers mutation semantics, authorization, and the terminal failure state. The one gap is return behavior: there is no output schema, so the description could say what calling it yields (e.g. the updated draft or a status), leaving the agent to discover the response shape.

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% with 13 documented properties, so the schema already carries parameter meaning. The description adds only the cross-parameter rule that array fields such as founders are replaced whole rather than merged, which is valuable but narrow; 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?

"Adds or corrects fields on an existing draft" gives a specific verb pair and resource, and the parenthetical plus the submit failure clause clearly separate it from create_incorporation_draft (new draft) and submit_incorporation (finalize). An agent can route correctly 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?

Usage conditions are clear: the draft must already exist, the caller must hold a verificationToken for the bound email, and the draft must not yet be submitted. It stops short of naming sibling tools as explicit alternatives, so the routing 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?

Adds meaningful context beyond the annotations: the token lasts ~30 minutes, re-verification issues a fresh token, and the same drafts remain reachable. Given the annotations already signal non-read-only, non-idempotent behavior, this is useful supplementary detail, though error/rate-limit behavior is not covered.

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 return value. Every sentence carries relevant information about token lifetime or downstream dependency.

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 appropriately explains the return value (verificationToken), its lifetime, and how draft tools consume it. For a simple two-parameter verification tool, 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?

Schema coverage is 100%, so both parameters are already documented in the input schema. The description mentions a 6-digit code and the email it was sent to, but adds no syntax or format detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource: verifies a 6-digit email code and returns a verificationToken. This clearly distinguishes it from siblings like request_email_otp and the draft tools that consume the token.

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 explicitly says the draft tools require this token, giving clear usage context. It does not explicitly name request_email_otp as the prerequisite step or state when not to use it, but the ordering is strongly implied.

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