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

Annotations indicate readOnlyHint=false (mutation), destructiveHint=false (not destructive), and idempotentHint=false. The description adds important behavioral details: the client is notified, existing items are untouched, and returns the updated intake. It doesn't mention potential side effects like rate limits, but the client notification is a key behavioral trait not captured in 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 short paragraphs: one for purpose with examples, one for behavioral notes, and one for validation rules. It is front-loaded with the core purpose, and every sentence adds value without unnecessary fluff.

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 2 parameters and an output schema, the description is mostly complete. It specifies the items schema references another tool, mentions notification and non-impact on existing items, and returns the updated intake. The only minor gap is not detailing validation failure behavior (e.g., partial additions), but the output schema and schema coverage mitigate this.

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 fully documents the parameters and their properties. The description adds minimal extra meaning beyond referencing 'same rules as define_intake' and the snake_case key requirement, but since the schema covers it, a 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 verb ('Add') and resource ('items to an intake'), and specifies the exact use case: adding items after an intake has been sent, with examples. It distinguishes itself from siblings like update_intake and define_intake by focusing on post-send additions.

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 use this tool: when you need to add items to an already-sent intake, and gives concrete examples. It also implicitly differentiates from define_intake (for initial definition) and update_item (for modifying existing items) by stating existing items are not affected.

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 the duplicate-name error condition, the uniqueness requirement, and the exact return payload. This gives the agent clear expectations about side effects and failure 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?

Every sentence earns its place: purpose, usage guidance, error condition, and return value. The most important routing instruction is front-loaded, and the description is compact without being vague.

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 with annotations and an output schema, the description covers the essential context: when to create, what happens on duplicates, and what the response contains. Nothing needed to invoke it correctly 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?

The schema already documents the 'name' parameter with uniqueness and examples, so coverage is 100%. The description adds the grouping use case but does not materially improve parameter 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 the tool creates a new folder to group intakes, with a concrete example ('one per client'). It distinguishes this tool from list_folders by framing creation as the fallback when no existing folder fits.

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 the agent to call list_folders first, reuse a matching folder, and only create when none matches. It also names the duplicate error and directs the agent back to list_folders, leaving no ambiguity about when to use this 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?

Beyond annotations, the description reveals important side effects: the invite email is sent, BriefGate chases the client automatically, and nothing pushes back because MCP is request/response. It also warns about the common failure of never checking, explains the follow_up block, and even flags the blank-name pitfall ('Hello,' to someone being asked for their admin password).

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 length is largely justified by 18 parameters, nested objects, and complex lifecycle behavior. It is front-loaded with the core purpose, then uses titled blocks and a concrete example; some content slightly repeats schema details, so it is not perfectly lean.

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?

Covers creation, the returned contract, follow-up setup, item and assignee semantics, naming constraints, and failure modes. An output schema exists, so the description does not need to enumerate return fields beyond the key { intake_id, portal_url, status, follow_up } shape. Nothing an agent needs to decide whether, when, or how to call it 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?

The schema already covers 100% of parameters, but the description adds substantial meaning beyond it: a full example intake, snake_case key rule, semantics for each item type, assignee='owner' behavior, proposal/decided_by flow, retention nuances, and chase cadence details. This materially improves an agent's ability to construct correct requests.

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 'Create a new client intake request — a branded portal where the client submits logos, copy, files, credentials, and other assets' with a specific verb, resource, and outcome. The create-vs-manage distinction is clear from 'Call this once at the start of a project' and from the sibling tool names like update_intake and add_items.

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 says to call this once at the project start after the needed assets are known, and gives detailed post-create guidance on setting up follow-up via webhook or schedule. It does not explicitly name alternatives like update_intake for modifying an existing intake, so exclusion guidance is implied rather than fully 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?

Annotations flag destructiveHint=true, readOnlyHint=false, and idempotentHint=false, and the description explains exactly why: secrets are decrypted and included only on the first call, later calls omit the value with first_reveal: false; files expire after 24 hours; and proposals are returned without include_pending yet don't bump revision, so they don't trigger only_new. This is rich behavioral disclosure fully consistent with 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 lengthy but well-structured: the purpose is front-loaded, and each paragraph addresses one distinct concern (files, secrets, flags, return shape, decision items). The explicit 'Returns { results ... }' block is partially redundant given the stated output schema, but every sentence carries distinct, non-fluff information that an agent needs.

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 tool with this much behavioral nuance — one-time secret reveal, signed URL expiry, and the interplay of proposals with only_new — the description covers the full calling surface: return shape, parameter effects, side effects, and edge cases like decided_by being 'owner' versus 'agent_proposal.' Nothing an agent needs to call it correctly 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 a baseline of 3 applies. The description adds real meaning beyond the schema: it explains only_new's 'since the last call' semantics and the revision/proposal nuance that affects it, and clarifies include_pending as partial-progress inclusion. intake_id is already self-explanatory from the schema, so the added value is concentrated but meaningful.

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 line 'Retrieve the typed submitted values from a client intake' uses a specific verb and resource, and it clearly distinguishes the tool from siblings like get_intake_status (status vs. values) and list_intakes. The remainder of the description reinforces exactly what data the tool returns (results plus meta), leaving no ambiguity about its core function.

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 concrete usage context: only_new is positioned 'useful in webhook-driven workflows,' include_pending is for 'partial progress checks,' and a precondition warns the user to be ready to receive a secret. However, it never names an alternative sibling or states when not to use this tool (e.g., versus get_intake_status), so explicit tool-routing guidance is missing.

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, so the safety profile is covered. The description adds meaningful context beyond that: it mentions the tool returns chase history and last-open time, and it specifies the scheduled-check behavior ('This is also the call a scheduled check should make when no webhook is registered'). This enriches the agent's understanding without contradicting 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 efficiently written, with the core purpose in the first sentence and usage guidance following. It is front-loaded and each sentence earns its place, though there is slight redundancy in restating 'Returns per-item status and chase history' after already listing those items. Overall, it is compact and well-organized.

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 tool with a single parameter and an output schema, the description covers purpose, usage scenarios, and the scheduled-check exception. It references the defining tool (define_intake) and the result tool (get_intake_results), giving the agent a clear workflow. The only minor gap is that it doesn't describe pagination or volume limits, but that is likely covered by the output schema and the tool's 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?

Schema description coverage is 100%, and the description does not add new parameter information. It only restates that intake_id comes from define_intake, which is already in the schema. The baseline of 3 for high coverage applies, as the description does not need to compensate for missing schema documentation.

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 ('Check the completion status of a client intake') and enumerates the exact information returned (submitted/pending/revision status, chase email history, last portal open). It also names sibling tools to route selection, distinguishing it from get_intake_results, send_chase, and request_revision.

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 states when to use this tool versus alternatives: 'Use this to decide whether to send a manual reminder (send_chase), request a revision (request_revision), or fetch results (get_intake_results).' It also provides a specific scheduled-check scenario with the cadence source ('follow_up in the define_intake response') and the follow-up action when status completes. No ambiguity.

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, so the safety profile is covered. The description adds the return structure (folders array with fields) and the reuse context, which goes beyond annotations. No contradictions. A 4 is appropriate because the description contributes useful behavioral context on top of 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 sentences, front-loaded with the purpose and immediately followed by usage guidance and return format. No fluff, every sentence earns its place. The structure is efficient and easy to scan.

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, parameterless read-only tool with an output schema, the description covers the purpose, usage timing, return structure, and even provides a reason to call it. Nothing an agent needs to invoke it correctly is missing. The description is complete and self-sufficient.

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 to describe. Schema coverage is trivially 100%. The baseline for 0 params is 4, and the description does not need to add parameter information since none exist. It correctly omits any param 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 clearly states it lists folders used for grouping intakes by client/project, with a specific verb and resource. It distinguishes itself from siblings by naming when to call it (before create_folder, etc.) and why (reuse existing folder). This fully clarifies the tool's purpose and differentiates it from 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?

The description explicitly instructs when to use the tool: 'Call this before create_folder or before setting folder_id on define_intake, update_intake, or list_intakes.' It also provides an anti-pattern (avoid creating duplicates) and names the alternative action (reuse existing folder). This is exemplary usage 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 carry readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description does not need to repeat those traits. It adds useful behavioral context by specifying account scope, optional filtering, and the exact response envelope with the fields included in each intake.

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 and front-loaded: operation and filters first, then use cases, then return shape. The use-case sentence is slightly longer than strictly necessary, but each listed scenario earns its place by clarifying when an agent should call this tool.

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 list tool with six optional filters and zero required parameters, this description is complete: it states the operation, gives decision triggers, names the related list_folders tool, and documents the response shape. Annotations cover the safety and idempotency profile, so the agent has enough 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?

The input schema has 100% parameter description coverage, including details like q substring matching, limit range, folder_id 'none' semantics, and default values. The description only summarizes the filter categories and adds no new parameter-level meaning, so the 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?

The first sentence clearly states the operation ('List all intakes in your account') and the filter dimensions available ('status, client email, folder, or a text search'). The return-shape sentence reinforces that this is a list-level tool, distinguishing it from single-intake siblings like get_intake_status and get_intake_results.

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: overviewing active projects, finding an intake by client email when intake_id is lost, counting in-progress intakes, and inspecting a folder from list_folders. It does not explicitly tell the agent when not to use this tool or route to single-intake alternatives, but the context is clear enough to guide selection.

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?

The description reveals important side effects beyond the annotations: it stops future reminders, clears the bounce flag, re-plans the schedule if the reinstated address was the only one being chased, and fails under specific conditions. This gives the agent a much clearer picture of what mutating the recipient list entails.

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 overall purpose, then unpacks each action in turn, and ends with failure conditions. There is no filler or repetition of schema text; every sentence contributes a distinct fact needed to choose and invoke an action.

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 present and annotations already signaling mutation, destructiveness, and idempotency, the description covers all operational essentials: action semantics, parameter roles, error conditions, and schedule re-planning. An agent has enough to call the tool 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 100%, so parameters are already documented. The description adds useful semantic detail by explaining what each action actually does to the recipient and when name is relevant, which goes beyond the schema's brief field 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 opening sentence names the resource (intake recipients) and the three operations (add, remove, reinstate), making the tool's purpose specific. It also distinguishes this from creation-time recipient setup by referencing 'also_notify does at define_intake time', so an agent understands this manages recipients after intake creation.

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?

Each action is tied to a concrete scenario: add invites, remove stops reminders, and reinstate clears a wrong bounce. The reference to define_intake's also_notify gives context for when this tool is the right post-creation choice, though it stops short of explicitly saying 'do not use for initial recipient setup'.

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 discloses that the signing secret is returned exactly once and cannot be shown again, that there is no rotation, and that the remedy is to delete and recreate. It also explains event semantics, including that intake.stalled only fires when max_reminders is set. This is rich behavioral context that annotations alone do not provide.

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 with clear paragraphs for usage, secret handling, and events. It is longer than average, but every sentence carries important information. The front-loading of the core purpose and the explicit usage condition is effective. Slight deduction for the event list being somewhat dense, but it 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?

Given the tool's complexity (5 params, 3 actions, 6 events, security implications), the description covers all critical aspects: when to use, what the secret is, event semantics, and action-specific parameter requirements. The output schema exists, so return values don't need explanation. Nothing essential is missing for an agent to invoke this tool 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 the baseline is 3. The description adds value by explaining the action-specific requirements (url required for create, webhook_id for delete), the meaning of the events array with a concrete example (["intake.completed"]), and the format options. It doesn't fully document every parameter's edge cases, but it meaningfully supplements 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 opens with a specific verb and resource ('Register, list, or remove a webhook endpoint') and immediately states the purpose: pushing intake events instead of polling. It clearly distinguishes itself from sibling tools like get_intake_status by naming the alternative and the condition that selects it.

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 use this tool ('ONLY if you control a service that can receive public HTTPS requests') and when not to ('An agent running in a terminal cannot — for that case do not register anything and check on a schedule with get_intake_status instead'). It also warns about the consequence of misuse (failing deliveries and false impression). This is exemplary usage 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?

The description discloses the key behavioral side effects: the client is notified automatically and the item status moves to needs_revision, and it returns a specific object { status: 'revision_requested', item_key }. These details go beyond the annotations, which only indicate non-read-only, non-idempotent, non-destructive, and open-world behavior. The description also implies a write operation that cannot be idempotent, which aligns 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 brief and front-loaded: the first sentence states the core action, the second gives usage context with examples, and the third reports the return value. No extraneous content; every sentence carries essential 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 description covers purpose, when to use, side effects, and return value. With the output schema already available and all parameters documented, this is sufficient for an agent to correctly invoke the tool in the expected workflow.

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 already describes all three required parameters (intake_id, item_key, note) with explanations, achieving 100% coverage. The description's examples (e.g., blurry logo, copy too long) illustrate usage but do not add new semantic constraints beyond what the schema provides, so it earns the baseline score.

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's action: asking the client to resubmit a specific item with an explanatory note. It provides concrete examples of what constitutes a revision-worthy item (blurry logo, overlong copy, broken URL), which helps the agent understand the intent. However, it does not explicitly differentiate from sibling tools like update_item, relying on the distinct verb 'request revision' rather than naming 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?

The description explicitly states when to use the tool: after reviewing get_intake_results and finding an item that does not meet requirements. It also notes the automatic client notification and status change to needs_revision. This gives clear usage context, but it doesn't provide when-not conditions or mention alternative tools such as update_item for direct edits.

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?

With annotations indicating it is not read-only (readOnlyHint=false), not idempotent, and not destructive, the description adds value by noting that the automatic schedule continues after this call, preventing the agent from thinking it disables automation. It also discloses the return value, though the output schema already provides that. The description doesn't mention potential side effects like duplicate reminders, but with the annotations, the bar is lower, and this is adequate.

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 with three sentences, front-loading the core purpose and usage context. It includes the return value in the last sentence, which is efficiently placed. No redundant information; every sentence contributes to understanding.

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 moderate complexity, the description covers purpose, usage, behavioral notes, and return value. The output schema already documents parameters and return type, so no further detail is needed. It could mention that channel is always 'email' but that's in the schema; the description is complete enough.

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

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

The schema already documents both parameters: channel is an enum limited to 'email', and intake_id references define_intake. The description does not add additional meaning beyond that, but since schema coverage is 100%, the baseline of 3 is appropriate. No further explanation is needed.

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 verb (send), the resource (reminder), and the context (manual nudge outside automatic schedule). It distinguishes itself from automatic reminders and from sibling tools like update_intake or get_intake_status, so an agent can confidently select it for this specific action.

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 specifies when to use: when a deadline is approaching and the client has not responded, or when SMS is needed after email failures. It also clarifies that the automatic schedule continues, so the agent knows this is an extra nudge, not a replacement. This directly guides decision-making among 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?

Beyond the annotations, it discloses critical side effects: including certain fields cancels all pending reminders and re-plans the schedule, raising max_reminders reactivates a stalled intake, and folder_id never touches the chase schedule. It also explains the email limitation and document attachment route, giving an agent accurate expectations.

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 every sentence carries operational value, and the main purpose is front-loaded before the caveats. It efficiently packs usage guidance, exclusions, side effects, and failure conditions without 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 tool with 13 parameters, nested objects, and significant side effects, the description covers input requirements, when to use alternatives, error conditions, and special cases like archived intakes and stalled reminders. The output schema exists, so not describing the return value is acceptable.

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 baseline is 3, but the description adds cross-parameter behavior not visible in the schema: the reminder re-planning trigger, max_reminders reactivation semantics, and null-clearing behavior for folder_id and client_brief. This adds genuine meaning beyond the individual 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 uses a specific verb and resource ('Change settings on an intake that has already been sent') and enumerates exactly which fields can be modified. It clearly distinguishes itself from siblings like define_intake and manage_recipients by stating what this tool can and cannot do.

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 instead of deleting and recreating an intake when deadlines or chase cadence change, and it names manage_recipients as the alternative for changing the client email. It also gives constraints: fails if archived and at least one field must be provided.

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' destructiveHint, the description discloses critical behavior: item keys are immutable because results are keyed by them, invalidating a submitted answer fails the call without side effects, and only discard_submitted_value: true clears the answer. This gives the agent a clear mental model of failure modes and idempotency.

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, then builds context through usage scenarios, a hard constraint, and failure semantics. Every paragraph serves a distinct function with no filler.

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

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

For a destructive 10-parameter mutation tool, the description covers the essential operational context: when to use it, what cannot change, how invalidations behave, and how to force a resubmission. The output schema covers return values, so nothing critical 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?

With 60% schema coverage, the description adds meaningful semantics for type switching, required flags, accepted formats, and the discard_submitted_value escape hatch. It does not elaborate on options or pattern, but the description significantly strengthens understanding of the key mutation parameters.

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 and resource: 'Change one item on an intake that is already with the client' and enumerates exactly which attributes can change (type, label, hint, required, accepted formats). This clearly distinguishes it from siblings like add_items and update_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?

It gives concrete when-to-use guidance ('Reach for this when the field turns out to be the wrong shape'), explains the alternative approach ('Add a new item instead' when the key must change), and details the discard_submitted_value workflow after a failed call. No ambiguity remains about when this tool is appropriate.

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