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

Beyond what the annotations provide (readOnlyHint=false, destructiveHint=false), the description discloses that the client is notified, existing items and submitted values are unaffected, and the updated intake object is returned. These are meaningful behavioral details that help an agent anticipate side effects without contradicting 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?

The description is tightly structured: first sentence states the core action with examples, second covers behavioral side effects, third gives the key constraint reference. No fluff or redundancy, and important information is 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?

For a two-parameter tool with fully documented schema properties, this description is complete. It covers when to use it, what happens on execution, return value, and item format constraints. An agent has enough context to invoke it correctly without additional inference.

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 high and both parameters are described in the schema. The description adds value by explicitly tying items to define_intake rules (snake_case keys, type-specific constraints) and giving practical examples of item types like favicon or credentials. This supplements the schema's generic descriptions.

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 operation: adding new items to an already-sent intake. It distinguishes itself from sibling tools like define_intake (creating an intake) and update_item (modifying an existing item) by focusing specifically on post-submission additions, reinforced by concrete examples.

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

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

The description gives a clear usage scenario: adding items mid-project after an intake has already been sent. It implies the alternative is define_intake for initial definitions, and even cross-references its item rules. It lacks an explicit exclusion statement, but the context is strong enough for an agent to select this tool appropriately.

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 signal that this is a write operation (readOnlyHint=false, idempotentHint=false). The description adds useful behavior beyond annotations by disclosing the folder_exists failure condition and the exact return shape, including fields like id, sort_order, and intake_count. It does not discuss permission requirements, but that is not a significant gap given 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?

The description is compact and front-loaded: it opens with the core purpose, immediately gives usage guidance with a sibling alternative, and closes with the failure mode and return shape. Every sentence adds value, and there is no redundant or filler content.

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 creation tool, the description is complete: it covers purpose, when to use, failure behavior, and return format. The output schema is absent, but the description compensates by listing the returned object fields. Annotations cover safety and world-openness, and no critical information is missing.

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

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

Schema description coverage is 100%, and the single 'name' parameter is well documented in the schema ('Must be unique in your account'). The description reinforces this with 'e.g. one per client' and mentions uniqueness implicitly via folder_exists, but it does not add substantial new parameter meaning beyond the schema. Baseline 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?

The description states a specific action ('Create a new folder'), a clear resource (folders for grouping intakes), and a concrete use case ('one per client'). It is clearly distinct from sibling tools like list_folders, and the title/description align without being tautological.

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?

Explicit guidance is provided: 'Call list_folders first and reuse a matching folder — only create one when none of the existing folders fits.' It also explains the failure case ('Fails with folder_exists... use list_folders to find it instead'), giving an agent clear decision rules for when to invoke this tool versus its sibling.

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?

It discloses several non-obvious behaviors: BriefGate automatically sends the invite and chases the client, nothing pushes to the agent, follow_up.recommended selects the completion mechanism, secrets are revealed exactly once, and owner items never block completion. These go well beyond the annotations, which only cover read-only/destructive/idempotency hints.

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 long, but the tool is complex and the length is mostly purposeful, with clear sections for the example, item types, and decisions. It is front-loaded with the core action and the most critical follow-up warning, though some content could be trimmed without losing value.

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 18 parameters, nested objects, and no output schema, the description supplies what the schema cannot: the return shape, follow-up workflow, failure mode, and parameter interaction rules. An agent has enough context to call this tool and wire up the resulting intake 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%, and the description adds substantial meaning on top: item type semantics, owner vs client assignee behavior, the proposed-answer concept for developer decisions, and a full worked example. It clarifies how 'secret' items behave and when 'structured' requires a JSON 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 opening sentence states a specific action ('Create a new client intake request') and describes the resource (a branded portal where the client submits assets). It also distinguishes this creation tool from follow-up siblings by noting the returned intake_id is needed for all follow-up calls.

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 to call it once at the start of a project after knowing the assets needed. It then tells the agent how to learn completion, naming get_intake_status and manage_webhook as the relevant alternatives, and warns against creating an intake and never checking again.

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 signal non-read-only and destructive behavior, and the description richly explains why: secrets are decrypted and revealed in plaintext only on the first call, then marked read with first_reveal:false and the value omitted. It also discloses the 24-hour signed-URL validity, the decision semantics (decided_by owner vs. agent_proposal), and the fact that reads do not bump revision. This goes well beyond the annotation hints and matches them consistently (no 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?

The definition is long (five paragraphs) but every section earns its place: base retrieval, signed URLs, the one-time secret reveal, the parameter flags, and the subtle decision behavior. The core purpose is front-loaded in the first sentence. The decision paragraph is dense but the underlying semantics are nuanced enough to warrant the detail; it could be tightened slightly without loss.

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?

There is no output schema, so the description correctly compensates by spelling out the return shape ({ results: {...}, meta: {...} }) including the meta sub-fields type/status/submitted_at/first_reveal and the decided_by field. Combined with the schema's parameter documentation, an agent has what it needs to call correctly. Minor gaps (no explicit error conditions or behavior when intake_id is invalid) keep it from a 5.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful extra semantics beyond the schema: only_new's interaction with revision (a read 'does not bump revision', so only_new surfaces exactly the decisions a person has since answered or changed) and the relationship between include_pending and proposed decisions. This adds real signal beyond the bare property definitions.

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 opening sentence 'Retrieve the typed submitted values from a client intake' states a specific verb, resource, and scope. It is clearly distinct from siblings like get_intake_status (status vs. values) and list_intakes (listing vs. retrieving a specific intake's submitted data). An agent can separate it from alternatives without opening a schema.

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

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

The description provides concrete usage context: only_new=true for webhook-driven workflows, include_pending=true for partial progress, and an explicit explanation of when a decision result is returned even without include_pending ('you need back the assumption you are building on'). It does not explicitly name alternative tools to avoid, but the purpose is sufficiently distinct that selection 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond these: it explains the return content (per-item status, chase history, last opened) and how the tool fits into a workflow (scheduled checks, follow-up routing). It does not contradict annotations; it complements 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?

The description is well-structured: the first sentence states the core purpose and key outputs, the second explains routing to alternatives, and the third adds the scheduled-check workflow. Every sentence contributes meaning without redundancy, and the most critical information is 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?

For a single-parameter read-only tool with no output schema, the description provides a solid overview of return data and usage scenarios. While it does not specify the exact structure of per-item status or chase history, this is a minor gap given the absence of an output schema; the description still enables an agent to call it correctly and understand the next steps.

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% for the single parameter intake_id, which already includes a clear description. The description does not elaborate on parameter usage or format beyond what the schema states, so it adds no extra semantic value. Baseline 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?

The description clearly states the tool checks the completion status of a client intake and enumerates the specific data it returns (per-item status, chase history, last portal open). It explicitly differentiates itself from sibling tools like send_chase, request_revision, and get_intake_results, so an agent can immediately understand its 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?

The description provides explicit when-to-use guidance: it is the tool to consult before deciding between send_chase, request_revision, or get_intake_results. It also specifies the scheduled-check use case when no webhook is registered, and instructs to fetch results via get_intake_results once status becomes 'completed'. This is thorough and actionable.

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 and idempotentHint, so the read-only nature is covered. The description adds the return shape (folders array with fields) and clarifies it's a listing operation, providing useful context beyond annotations.

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

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

Three concise sentences, each serving a distinct purpose: purpose, usage guidance, and return format. No fluff 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?

For a parameterless, read-only tool with no output schema, the description covers everything an agent needs: what it returns, when to call it, and why. It's complete for its simplicity.

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

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

There are zero parameters, so the schema fully covers all inputs. With no parameters to document, the baseline of 4 applies; the description doesn't need to add parameter details.

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 'folders in your account', plus explains the purpose 'group intakes by client or project'. This clearly differentiates it from sibling tools like create_folder, and the mention of 'List' makes it obvious it's a read operation.

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?

Explicitly instructs to call before create_folder or before setting folder_id on other tools, and advises reusing existing folders to avoid duplicates. This is direct when-to-use guidance with a clear rationale.

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 carry readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is fully covered. The description adds the response shape and the folder 'none' convention, but pagination, ordering, and other runtime behaviors are not disclosed beyond what the schema already states. With annotations covering safety, this is adequate but not rich.

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 paragraphs with no waste: purpose, use cases, and return format. The core verb and scope are front-loaded in the first sentence. Each paragraph serves a distinct function, and the description remains compact despite covering multiple optional filters.

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?

Although there is no output schema, the description explicitly states the response shape and the fields each intake includes. With 100% parameter schema coverage, rich read-only annotations, and sibling context, an agent has everything needed to invoke the tool correctly. No critical gap is evident.

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 each of the 6 parameters already fully described. The description's filter summary (status, client email, folder, text search) merely restates schema dimensions without adding new semantics, constraints, or usage nuances. The baseline of 3 applies because the schema carries the parameter documentation 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?

The description begins with 'List all intakes in your account, optionally filtered by status, client email, folder, or a text search,' which states a specific verb, resource, scope, and filtering options. It clearly distinguishes this multi-intake listing tool from siblings like get_intake_status, which presumably targets a single intake.

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 second paragraph gives concrete use cases: overview of active projects, finding an intake by client email when intake_id is lost, counting in-progress intakes, and viewing folder contents. It references list_folders as the source for folder_id, which helps route preparation steps. It does not explicitly state when not to use this tool or name alternatives to avoid, so it stops short of full exclusion 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?

Beyond annotations, the description explains that this is a two-phase flow, that the first call returns a URL and code, that re-calling checks approval status, and that the key is stored locally once approved. It also discloses that it has no effect when env/flag auth exists and that the hosted endpoint auto-triggers OAuth, giving a very complete behavioral picture.

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?

Although the description is long, it is necessary for a non-trivial two-phase flow. It is well-structured with a summary, trigger conditions, numbered phases, and explicit exclusions. Every sentence carries operational information, and the key trigger condition is 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?

For a multi-phase tool with no output schema, the description covers the full flow: what happens on first call, what the agent should tell the user, what happens on subsequent calls, and when the tool is not applicable. An agent has enough information to call it correctly and to guide the user through approval.

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, so the input schema leaves nothing to document; the baseline for no parameters is 4. The description reinforces this by saying repeated calls use 'no arguments change,' which is helpful for agents deciding how to invoke the second phase.

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 the specific action ('Sign in without pasting an API key') and the mechanism (browser-based human approval, then local key storage). It is clearly distinct from siblings like logout and the rest of the toolset, and even references a comparable flow (snyk_auth) to anchor meaning.

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 when to call this tool: 'whenever a tool reports “Not signed in” or that the stored key was revoked or expired.' It also gives exclusions: if an API key flag or environment variable is present, and if running on the shared hosted endpoint, the tool should not run the flow.

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

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

The description goes well beyond the annotations: it explains the local removal, the server-side DELETE call, the best-effort revocation behavior, what happens when the revoke fails, and where to revoke manually if needed. This aligns with and enriches destructiveHint and readOnlyHint rather than merely repeating 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?

Three compact sentences pack in the action, the HTTP detail, the failure mode, the fallback guidance, and the availability constraint. Every sentence earns its place and there is no redundant wording.

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, no-output-schema tool, the description is complete: it covers what happens, how it happens, what happens on failure, and when it cannot be used. No critical information is missing for an agent to invoke 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?

The tool has zero parameters, so there is nothing for the description to add beyond the schema. Baseline 4 is appropriate because the description correctly focuses on behavior instead of inventing parameter details.

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 action: remove the locally stored API key and best-effort revoke it on the server. It also distinguishes itself by explaining exactly what is modified, so an agent can clearly tell logout from the sibling login 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?

The description provides clear behavioral context and an explicit when-not: the tool is unavailable on the shared hosted endpoint. It does not explicitly contrast with alternatives, but for a logout operation the purpose is unambiguous and the failure mode is fully explained.

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?

Beyond the annotations, the description discloses meaningful side effects: remove stops future reminders, reinstate clears a bounce flag and may re-plan the schedule, and add creates its own message and bounce state. It also explicitly states failure conditions for non-member addresses and reinstate on non-bounced addresses.

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 front-loaded with the core purpose and then organized by action, with each sentence earning its place. It is dense but not bloated, and the failure conditions are placed at the end as a natural close.

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 mutation tool with no output schema, the description covers the three actions, side effects, scheduling implications, and failure cases. It does not describe the success return value, but that is a minor gap given the detail present for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by explaining the semantics of each action value, noting that name is only used with add, and clarifying how email/intake_id relate to failure conditions. This goes beyond the schema's terse property descriptions.

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 opens with a specific verb set — add, remove, or reinstate — and names the resource (a person receiving an intake's invite and reminders). It clearly distinguishes this tool from siblings like define_intake and update_intake by framing it as managing recipients alongside or instead of the primary client.

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

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

The description gives clear context for each action and even references define_intake's also_notify behavior to explain the add case. It does not explicitly list alternatives or say 'use this instead of X', but the action-specific guidance makes the intended use obvious enough.

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 signal destructive/non-read-only behavior, but the description adds substantial context: the create action returns a one-time secret, the secret cannot be retrieved again, there is no rotation, and unreachable endpoints create false delivery confidence. It also documents conditional event behavior such as intake.stalled only firing with max_reminders set.

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 long but tightly organized: purpose, usage restriction, secret lifecycle, then event definitions. Every sentence carries operational weight, and the most important usage constraint is 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?

For a webhook manager with no output schema, this is highly complete: it covers when to use the tool, when not to, secret handling, event semantics, format options, and action-specific parameters. Nothing necessary for correct invocation 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 the baseline is 3; the schema already describes url, action, events, format, and webhook_id. The description adds some operational meaning, like the secret-on-create behavior and an events example, but it does not need to carry much of the parameter-semantics 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?

The description states a specific verb-and-resource relationship: register, list, or remove webhook endpoints so BriefGate pushes intake events instead of polling. This clearly distinguishes the tool from the polling-based sibling get_intake_status.

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 explicitly says this tool should only be used when the agent controls a public HTTPS-receiving service, and warns that terminal agents must instead poll with get_intake_status. It also gives concrete event-selection guidance, such as using ["intake.completed"] for client-completion scenarios.

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?

Beyond annotations, the description discloses that the client is notified automatically, the item status moves to needs_revision, and the return value is { status: "revision_requested", item_key }. This gives the agent a full picture of side effects and outcome without contradicting 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?

The description is compact and front-loaded: the primary action comes first, followed by the triggering condition with examples, then the side effect and return value. Every sentence contributes necessary information without 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 tool has no output schema, but the description supplies the return shape. It also covers prerequisites via the workflow reference to get_intake_results, and the schema links intake_id to define_intake. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description reinforces that the note explains what is wrong but adds little semantic value beyond the schema's own parameter descriptions.

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: ask the client to resubmit a specific item with a note. It includes concrete examples (blurry logo, long copy, broken URL) and describes the resulting status change, making the tool's role unambiguous even without naming sibling alternatives.

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 explicitly says to use this after reviewing get_intake_results and finding an item that does not meet requirements. It does not discuss when-not-to-use or contrast with update_item or send_chase, but the workflow context is clear.

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

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

The description adds useful behavioral context beyond the annotations: the automatic chase schedule continues after this call, and the call returns { sent: true }. It does not warn about duplicate sends, but idempotentHint=false already covers that. The SMS mention conflicts with the schema's email-only channel, which slightly weakens 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 concise and front-loaded with the main action, followed by use cases and the return value. Every sentence contributes something, though the SMS sentence is confusing and could be removed or corrected. Overall it is efficient and well-structured.

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 two-parameter tool, the description covers the main behavior, use cases, and return value. The missing piece is the contradiction between the SMS mention and the email-only channel, which is significant because it affects how the agent should invoke the tool. The schema covers the intake_id prerequisite, so no major gap there.

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 both parameters well. However, the description says an SMS can be sent after email failures, while the channel parameter only allows 'email'. This actively misleads the agent about valid parameter values, so the description detracts from rather than adds to parameter semantics.

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 core action: sending a manual reminder outside the automatic schedule. It differentiates the tool from sibling intake/list tools and from the automatic chase flow, though it does not name a specific sibling alternative. The mention of sending an SMS after email failures introduces some ambiguity about the tool's actual delivery scope.

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

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

The description gives explicit conditions for use: when a deadline is approaching, when automatic reminders got no response, or after email attempts failed. It also clarifies that this is an extra nudge and not a replacement for the automatic schedule. It does not explicitly list when not to use it, but the provided context is actionable.

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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description discloses the key side-effect: including any of eight listed fields cancels all pending reminders and replans the schedule from now, with already-sent reminders still counting toward max_reminders. It also documents the stalled-intake reactivation behavior, that folder_id 'never touches the chase schedule', and the archived-intake failure condition. 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?

Eight sentences, each earning its place: purpose, use case, side effects, exclusions, per-field notes, constraints, return value. Despite its length, nothing is redundant with the schema, and the most decision-relevant information (replanning trigger, email exclusion) appears early and prominently.

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 tool with nested objects and no output schema, the description covers all invocation requirements: required intake_id, the at-least-one-field rule, failure conditions ('Fails if the intake is archived'), return shape, and side-effect semantics. An agent can invoke it correctly using only this text plus 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 100%, so the baseline is 3. The description earns a 4 by adding cross-parameter semantics the per-field schema entries don't convey: the exact list of fields that trigger reminder replanning, the interaction between raising max_reminders and reminders already sent, and the guarantee that folder_id is independent of the chase schedule.

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 opening sentence names a specific verb ('Change') and resource ('an intake that has already been sent') and enumerates the editable fields. It is further differentiated from sibling tools like define_intake (creating), manage_recipients (email), and add_items/update_item (items), so an agent can select it unambiguously.

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 'Use this instead of deleting and recreating the intake when a deadline moves or the chase cadence needs to change' and names manage_recipients as the alternative for email changes. It also tells the agent what not to use it for (brief documents go through REST/dashboard) and states failure preconditions (archived intakes).

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

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

Annotations only declare destructiveHint=true and readOnlyHint=false. The description goes far beyond by detailing the exact failure mode (invalidating a submitted answer), the effect of discard_submitted_value, and the guarantee that nothing is touched on failure. It also clarifies that a non-invalidating change never discards answers. 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?

The description is three paragraphs but every sentence carries purpose. It is front-loaded with the core action, then usage, constraints, and failure handling. It is slightly longer than strictly necessary but not bloated, and the structure is logical.

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's complexity (10 parameters, mutation with destructive hint, failure modes), the description covers all critical aspects: what it does, when to use, key constraints (immutable key), failure handling, and parameter semantics for the most important parameters. No output schema exists, so return values need not be described. The description is sufficient for correct invocation.

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

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

Schema description coverage is 60%, so the description must compensate. It explains the semantics of key parameters: type, label, help (hint), required, constraints (file formats), and discard_submitted_value in detail. However, it does not clarify pattern or options, which remain under-documented. Overall it adds meaningful meaning 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 states a clear verb ('Change') and specific resource ('one item on an intake') and enumerates the editable fields (type, label, hint, required, file formats). It also distinguishes from sibling tools by noting it edits existing items already with the client, versus add_items or define_intake. 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?

Explicit when-to-use guidance is given with concrete examples ('field turns out to be the wrong shape'), plus a clear alternative ('Add a new item instead') for changing the item key. It also explains the failure condition (client already answered and change invalidates their answer) and how to proceed (discard_submitted_value). This fully routes an agent.

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