gvrn-incorporation

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

Annotations are sparse (readOnlyHint, idempotentHint, destructiveHint all false). The description adds that the draft is bound to the verified email and returns a draftId. However, it does not disclose what happens if a draft already exists for that email or if the call has any side effects beyond creation. More behavioral context would improve transparency.

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 description is two sentences long, each serving a distinct purpose: stating the creation action and required field, then mentioning the return value. No redundant information, well front-loaded.

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

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

Given the tool has 12 parameters, 100% schema coverage, no output schema, and siblings indicating a workflow, the description covers the basics. However, it omits potential constraints (e.g., one draft per token, error conditions) and does not clarify if creating a new draft overwrites an existing one. More detail would enhance completeness.

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

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

Schema description coverage is 100%, so the input schema documents each parameter thoroughly. The description adds minimal extra meaning beyond noting the verificationToken as required and the return of draftId. It does not elaborate on any parameter beyond what the schema provides.

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

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

The description clearly identifies the tool's action ('Creates a new incorporation request draft'), the resource ('draft bound to the verified email'), and distinguishes it from siblings like update_incorporation_draft and submit_incorporation.

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 states the required parameter ('Requires a verificationToken from verify_email_otp') and that all other fields are optional. It gives context on the tool's role in the workflow (creates a draft for later updates and submission), though it could contrast more directly with update_incorporation_draft.

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, indicating a safe read operation. The description adds detail on what the guide contains (fields, steps, lifecycle), which supplements the annotation effectively. No contradictions.

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 description is two sentences, front-loaded with the action 'Returns', and includes only essential information. No unnecessary words or 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?

Given no parameters and no output schema, the description provides sufficient context about what the guide covers. It mentions key elements (fields, verification steps, lifecycle) so the agent knows what to expect from the return value.

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

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

There are zero parameters, so the description does not need to add parameter-level meaning. The schema coverage is 100% by absence. Baseline 4 for no parameters 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?

The description clearly states it returns the incorporation workflow guide, specifying the contents: fields, email-verification steps, and review lifecycle. It distinguishes itself from sibling tools like create_incorporation_draft or submit_incorporation by being a read-only informational resource.

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 explicit when-to-use or when-not-to-use guidance is given, but the context of being a guide makes its usage obvious: to understand the process before performing other actions. The mention of an alternative MCP resource form provides a minor alternative.

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. The description adds important behavioral context: requires a verificationToken tied to the email that created the draft, and requests are only visible to that email. This goes beyond annotations without contradicting them.

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-load the purpose and status list, with no wasted words. Every sentence earns its place.

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

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

For a simple status check tool, the description covers purpose, parameters, and access constraints. Minor gap: no mention of the return format (e.g., just the status enum or full object), though the status list implies the response content.

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% with descriptions. The description adds value by linking draftId to 'create_incorporation_draft' and verificationToken to 'verify_email_otp', providing inter-tool context for parameter origins.

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 clearly states it returns the status of an incorporation request and lists the possible statuses (DRAFT → QUEUED_FOR_REVIEW → UNDER_REVIEW → COMPLETED). This specific verb-resource combination distinguishes it from sibling tools like create_incorporation_draft, submit_incorporation, etc.

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

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

The description implies usage after creating a draft and verifying email, and notes the access restriction (only visible to that email). It does not explicitly state when not to use, but the context is clear enough given sibling tool names.

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 indicate mutation (readOnlyHint=false) but non-destructive. The description adds that codes expire after 10 minutes and are rate-limited per email, which supplements the annotations without contradiction.

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, no wasted words. Information is front-loaded: action, purpose, flow, constraints. Excellent efficiency.

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 simple one-parameter, no-output-schema tool, the description covers action, flow, expiration, rate-limiting, and integration with sibling tools. Entirely adequate.

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 input schema has one parameter with full description coverage. The description adds the context 'the user's real inbox', reinforcing the email purpose meaningfully beyond 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 clearly states it sends a 6-digit code to an email and explains its role in the verification flow (exchanged for a token via verify_email_otp, authorizes draft tools). It distinguishes itself from the sibling tool verify_email_otp.

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 states the flow: send the code, then use verify_email_otp to exchange it. It provides clear context for when to use this tool (before verify_email_otp), though it doesn't explicitly mention when not to use it.

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 indicate destructiveHint=true, and the description adds specific behavioral details: the draft becomes read-only and a review request is filed, explaining what 'destructive' entails. No contradiction with 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?

Three concise sentences that front-load the main purpose and progressively add essential constraints. No unnecessary words or redundancy.

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 description mentions 'returns the request status' but does not specify the format or content of that status, leaving ambiguity. Given no output schema, more detail would improve completeness. Otherwise covers prerequisites and irreversibility.

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% with descriptions for draftId and verificationToken. The description adds that draftId comes from create_incorporation_draft and verificationToken from verify_email_otp, but this is minimal additional insight beyond 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 clearly states the action ('Submits a draft for review') and the resource ('draft'). It distinguishes from siblings like create_incorporation_draft and update_incorporation_draft by emphasizing submission and irreversibility.

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 provides context on when to use the tool (after creating a draft and verifying email with OTP) by mentioning the required verificationToken. However, it does not explicitly state when not to use it or name 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 provide idempotentHint=true and destructiveHint=false. The description adds patch semantics, the verificationToken requirement, and the failure upon submission, which are valuable behavioral insights beyond annotations.

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

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

The description is three concise, front-loaded sentences. Every sentence adds distinct value: purpose+semantics, authentication requirement, and lifecycle constraint. No wasted words.

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

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

Given 13 parameters, no output schema, and sibling tools, the description adequately covers core behavior, authentication, and lifecycle. It doesn't detail error handling or success responses, but that's acceptable given the tool's complexity and lack of output schema.

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

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

Schema description coverage is 100%, so the schema already documents each parameter. The description adds semantic context like patch behavior and array replacement, enhancing understanding beyond 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 clearly states it adds or corrects fields on an existing draft with patch semantics, distinguishing it from create_incorporation_draft (creation) and submit_incorporation (submission). The verb 'updates' plus specific behavior details provide excellent clarity.

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 mentions it requires a verificationToken and fails after submission, implying use before submission. It lacks explicit 'when not to use' or alternative naming, but the context from siblings and the description itself gives sufficient 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?

Adds behavioral info beyond annotations: token validity of ~30 minutes and the effect of re-verifying (fresh token for same drafts). No contradictions with 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 concise sentences that front-load the core action and output, with no wasted words.

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 only 2 parameters and no output schema, the description adequately explains the return value (verificationToken) and its usage context (draft tools). Complete for the tool's complexity.

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 covers both parameters fully with descriptions. Description does not add extra meaning beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

Description clearly states the verb 'verifies' and the resource '6-digit email code', and explains the output 'verificationToken'. It distinguishes from sibling request_email_otp by specifying the action of verification.

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?

Implicitly tells when to use: after receiving the code and to obtain a token for draft tools. Does not explicitly state when not to use, but context from sibling tools provides clarity.

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