Democruit

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

Annotations declare destructiveHint=true and non-idempotent, and the description adds the crucial missing context: fixes require explicit conversation confirmation, must be previewed first, and the caller should follow the primary nextAction in the envelope. It does not describe what exactly gets overwritten by a fix, but the gating behavior is well disclosed.

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?

Front-loaded with purpose, then operations, then the confirm protocol; nearly every sentence earns its place within four short sentences. The one wasted/incorrect element is the listing of an operation ('uploaded') that does not exist in the schema.

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

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

For a 14-parameter, multi-operation, destructive tool with a full output schema, the description covers the high-risk flow (preview/confirm/nextAction) adequately. It still leaves the operation semantics thin, and the operation list contradicts the enum, so an agent can't fully rely on it.

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 would be 3, but the description lists operations as 'check | uploaded | report | fix' while the schema enum allows only check, report, fix. An agent following the description could pass operation: "uploaded" and fail validation — a defect in the most important parameter.

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 concrete verbs and resources — check a saved resume or uploaded PDF, read its report, apply report-supported fixes — so the agent knows exactly what the tool family does. It does not differentiate itself from close siblings like summarize_resume or get_resume_statistics, which is the only thing keeping it from a 5.

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

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

The confirm:false preview → repeat with confirm:true protocol is spelled out precisely, which is genuinely useful guidance for the destructive branch. However, the description never says when to choose check vs report vs uploaded, nor when to prefer this over sibling tools such as summarize_resume, so the routing guidance is only partial.

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 that new letter generation is unconfirmed, existing wording is not overwritten, application kits need an idempotency key, and the response envelope should drive the next action. These are meaningful behavioral details not captured by readOnlyHint, destructiveHint, or openWorldHint. The confirmation workflow is somewhat undermined by referencing a `confirm` parameter that does not appear in the schema.

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 purpose and operations, and most sentences carry useful constraints. The operation list is long but appropriate for a multi-operation tool. It is slightly weakened by the later confirmation sentence introducing a schema mismatch.

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

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

The tool is complex with 25 parameters, an output schema, and multiple operations. The description covers confirmation, idempotency, and nextAction handling, but it does not explain which fields apply to which operation and references a non-existent confirm flag. Given the schema richness, this is adequate but leaves important operation-specific gaps.

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 parameters and enums; the description adds little parameter-level detail and does not map operations to their required fields. Worse, it instructs the agent to use `confirm: false` then `confirm: true`, but `confirm` is not defined in the input schema and additionalProperties is false. This creates a concrete parameter invocation error.

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: creating career documents or tracking applications. It enumerates the supported operations and clarifies that existing wording is never overwritten here, which helps distinguish it from update-oriented siblings. An agent can identify the tool's scope without opening the schema.

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

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

The description gives clear usage conditions: new letter generation needs no confirmation, application kits require an idempotency key, and previews should be followed by confirmation. It also implies that edits to existing wording belong elsewhere. However, it does not explicitly name alternatives such as update_item or list_items, so routing relies partly on inference.

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 destructiveHint/idempotentHint annotations, it discloses permanence, the mandatory conversation confirmation, the preview-then-commit pattern, and that the return is an envelope whose 'primary nextAction' should be followed. These are non-obvious behaviors an agent cannot infer from structured fields.

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?

Front-loads the destructive effect, then the confirmation constraint, then the operation list and return handling. Dense but every clause carries information; the pipe-delimited operation list is compact rather than verbose.

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 destructive tool with an output schema and full annotation coverage, the description supplies everything else an agent needs: confirmation gating, preview workflow, operation scope, and nextAction handling. No material gap remains.

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 the operative semantics of `confirm` (preview vs commit) and that inputs must be identical between the two calls. The operation-per-field mapping is only partially restated ('Each operation accepts only its own fields' is in the schema only).

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

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

States a specific verb and effect ('Permanently delete the selected saved information') and enumerates the exact operations scope. It is clearly distinguishable from read-side siblings like get_item/list_items and from update_item, though it never names an alternative directly.

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

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

Gives a concrete two-step protocol: 'Use confirm: false for a preview, then repeat identical inputs with confirm: true after the user confirms.' That is real when/how guidance, but it omits when an agent should prefer update_item or a restore path over deletion.

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 readOnly/idempotent/non-destructive, and the description adds real value on top: it clarifies no external side effects occur, describes the preview-then-confirm pattern, and points to the response envelope's nextAction. The confirm flag it references is not present in the schema (additionalProperties: false), which is a real inconsistency that costs a point.

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

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

Four tight sentences with the core purpose, the negative scope, and the operational flow front-loaded. Every sentence carries information, though the trailing confirm instruction is the weakest given the parameter is absent from the schema.

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

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

An output schema exists, so return-value detail is unnecessary, and the description still helpfully points to nextAction in the envelope. For a 12-parameter, multi-operation tool the description covers purpose, safety, and flow adequately, with only the phantom 'confirm' field left unresolved.

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 12 parameters and the operation enum, setting the baseline at 3. The description names the four operations but adds no field-to-operation mapping beyond the schema's own 'Each operation accepts only its own fields,' and its mention of an undocumented 'confirm' parameter adds confusion rather than clarity.

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 (draft) and concrete resources (career email, LinkedIn copy, resume bullets) and enumerates the four operations. No sibling tool drafts text, and the description makes that scope unambiguous without opening the schema.

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

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

Explicitly states what it will not do ('does not save, send email or post externally') and prescribes a two-step confirm flow ('confirm: false for a preview... then repeat identical inputs with confirm: true'). It stops short of routing to a named alternative sibling, which keeps it from a 5.

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

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

Annotations already disclose readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false. Beyond that, the description usefully adds the read+write permission requirement and the 'follow the primary nextAction' envelope contract. However, the central behavioral instruction (confirm:false preview, then confirm:true) cannot be executed because no such parameter exists, which undermines the disclosure.

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

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

Four tight sentences with the purpose, permissions, operation list and workflow front-loaded in that order. Minor waste in restating the operation enum verbatim, but nothing is padded.

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, the description is right not to explain return values, and it correctly calls out the permission requirement for a multi-operation generator. The gap is that the two-step confirmation flow is unexecutable as written, leaving the agent without a valid preview/confirm procedure for a non-idempotent write operation.

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

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

Schema coverage is 100%, so all five parameters are already documented and the baseline would be 3. The description's only parameter-level addition is the non-existent 'confirm' flag, which actively misleads rather than informing; the operation list simply repeats the enum. Introducing a phantom parameter is worse than adding nothing.

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 concrete verb and resource ('Generate a PDF of a saved document or report') and enumerates the four supported operations, so an agent knows exactly what it produces. It does not name or distinguish any sibling tool, though no sibling in the list also produces PDFs, so confusion risk is low.

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 workflow and prerequisite guidance ('Requires both read and write access', preview-then-confirm) but never says when to choose this over alternatives or what the preconditions are for each of the four operations. The preview/confirm advice references a 'confirm' parameter that does not exist in the input schema (additionalProperties: false), so an agent following it verbatim would fail validation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds that a response envelope is returned and the primary nextAction should be followed, which is helpful, but the 'confirm: false preview, then confirm: true' instruction implies a state-changing, confirmation-gated operation that conflicts with the declared read-only/idempotent profile.

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 with the purpose front-loaded. But the final sentence is wasted on impossible confirm-parameter instructions, costing more than it saves.

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

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

An output schema exists, and the description appropriately points to the envelope and primary nextAction rather than restating return values. Still, for a single-enum-parameter tool the description leaves the operation tradeoffs unexplained while injecting confusing confirm guidance, so it is only adequate.

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

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

Schema coverage is 100% and the enum values are already self-documenting, so the schema needs no help. Instead, the description adds a 'confirm' parameter that does not exist in the schema (additionalProperties: false, only 'operation' accepted), which actively misleads rather than adding meaning.

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 states a specific verb and resource ('Check remaining ... allowance') and enumerates the three operations, so an agent can tell it apart from siblings like get_pass_pause_preview or get_resume_statistics. It is clear but does not explicitly contrast itself with those adjacent tools.

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 lists the operation choices and gives a preview-then-confirm workflow, which implies usage context. However, it never says when to pick pass vs research vs interview, and the confirm instructions reference a parameter that cannot be supplied (see schema/additionalProperties: false), so the guidance is partly unusable.

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 readOnly/idempotent annotations it usefully discloses the response-envelope + nextAction pattern and the polling field (pollStartedAt), which an agent needs to chain calls. However the "confirm: false … then confirm: true" instruction describes a two-step commit flow with no readOnly equivalent and references a parameter that does not exist in the schema, which is confusing for a tool annotated as a pure read.

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?

Front-loaded with the core action and four short, information-dense sentences with no filler. The inline operation enum duplicates the schema's enum and could be dropped 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?

With 12 parameters, an output schema and full annotations, most structured burden is already carried, and the description covers the detail flag and the nextAction loop. But it omits ID selection behavior across the multiple per-type IDs and references a nonexistent confirm flag, leaving the agent to reconcile the description against 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 adds real value only for detail=true and the nextAction/polling handshake. It also introduces a `confirm` parameter absent from the schema, which actively misleads rather than clarifies.

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?

"Read one saved item" is a specific verb+resource and the appended operation list makes the breadth of item types explicit, which separates it from list_items. It never names update_item or list_items, so the boundary with siblings is implied rather than stated.

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

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

It gives concrete usage conditions: set detail=true before editing, use confirm:false for preview then repeat with confirm:true, and follow the primary nextAction from the envelope. It stops short of saying when to prefer list_items (multiple items) or update_item (to make the edit), which would complete the routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds useful scope context (this is preview-only; the mutation lives in Democruit settings), but the remainder of the text just enumerates return fields, which the output schema already owns.

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

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

Three short sentences, front-loaded with purpose followed by the scope caveat and then the return summary. No filler and nothing buried.

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 rich annotations, a full output schema, zero required params and complete schema descriptions, the definition is nearly self-sufficient. The only meaningful gap is not mentioning that the keep-selection options may be paginated via 'cursor', which could lead an agent to report a partial list as complete.

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

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

Both optional parameters are documented at 100% schema coverage, including the guidance to omit them by default, so the schema carries the burden. The description adds nothing about how 'cursor' affects paging through keep-selection options, which is the one place extra meaning would have helped.

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

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

The description gives a specific verb ('Preview') and a specific resource ('whether an annual pass can be paused and which documents remain available'), so the agent knows exactly what comes back. It also scopes the tool by stating the actual pause happens in Democruit settings, which separates it from a mutating sibling like reactivate_annual_pass, though it never names that sibling.

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

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

Usage context is clear: call this to check pause eligibility, and the pause itself is performed elsewhere in Democruit settings, which prevents the agent from expecting a write. It stops short of explicitly contrasting with reactivate_annual_pass or saying when a preview is unnecessary.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds one genuine behavioral fact — the result spans all available history with no filtering — but says nothing about result volume, pagination, or latency for what could be a large unbounded read.

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

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

Three short sentences, front-loaded with purpose, which is good. But "over the service's available history" and "There is no date-range filter" restate the same fact, and "Returns: resume viewing statistics" is near-tautological given an output schema exists.

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, annotations covering the safety profile, and a single fully-documented optional parameter, the description covers what the agent needs to invoke it correctly. Only the unbounded-history result volume is left implicit.

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 resumeId property already documents the omit-when-single-item behavior thoroughly. The description contributes nothing about the parameter, so the baseline 3 applies — the schema does all the work.

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

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

States a specific verb and resource ("Show recorded view statistics for a saved resume") with an explicit scope ("over the service's available history"). It is clearly distinguishable from siblings like get_item, list_items, or summarize_resume, though it never names an alternative to reinforce that.

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 only usage guidance is the negative constraint "There is no date-range filter," which tells the agent it cannot scope the query but not when to prefer this tool over get_item or list_items. Usage is implied by the name rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered; the description adds the envelope/nextAction convention, which is useful. However, the 'confirm: false for a preview, then repeat identical inputs with confirm: true' instruction describes a gated mutation flow that makes no sense for a read-only getter and is not supported by the schema (no confirm parameter exists), which would actively mislead an agent.

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 operation list and the first-contact rule are front-loaded and compact, which is good structure. But the trailing confirm/preview sentence is wasted and incorrect content in an otherwise tight definition, so it does not fully earn 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?

An output schema exists, so return values need not be explained, and the envelope/nextAction hint is a reasonable pointer. The definition is still incomplete for correct invocation because it tells the agent to pass a nonexistent confirm parameter and never clarifies how the three operations relate to the sibling tools.

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 would be 3 even with no parameter prose; here the description does not merely stay silent, it introduces a phantom 'confirm' argument that does not exist in the schema (additionalProperties: false), and adds nothing about cursor or detail that the schema does not already state.

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 concrete verb plus resources ('View the career workspace, profile, or suggested next task') and enumerates the three operations, so an agent understands the resource it reaches. It does not differentiate this tool from nearby siblings like get_item, list_items, or summarize_resume, so it stops short of a 5.

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

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

It gives explicit sequencing guidance ('On first contact use summary to check onboarding before continuing the requested task') and names the operation set, which is more than most definitions offer. It never states when to prefer this tool over the sibling readers (get_item, list_items), leaving that routing to inference.

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 real behavioral context beyond the annotations: a turn-based protocol keyed on nextAction, expiry recovery via the retained entity, and the full set of user actions. However, it instructs the agent to 'use confirm: false ... then repeat identical inputs with confirm: true', and no confirm parameter exists in the schema (additionalProperties: false), so this guidance would lead an agent to send an invalid argument.

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 purpose is front-loaded and most sentences carry real protocol information, but the closing confirm sentence is both verbose and factually wrong, and phrasing like 'follow the primary nextAction' assumes vocabulary the agent only learns from the response envelope.

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

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

An output schema exists, so return values need not be explained, and the description correctly points at the response envelope and nextAction. It does not explain how the guided sequence terminates or what the agent should do on an expired draft beyond 'retain entity', and the incorrect confirm instruction leaves the write/commit path undefined.

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 would be 3, but the description actively misleads: it names a 'confirm' parameter that is not in the schema and cannot be passed. The useful addition (entity seeds a start, draftId/revision/questionId come from prior turns) is present but is undercut by the phantom parameter.

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 concrete verb and workflow: 'Collect real facts one question at a time' and the two operations (start | answer). An agent can tell this is a multi-turn guided data-entry tool. It does not, however, distinguish itself from siblings such as draft_text or create_item, which also produce content from user input.

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 sequencing is explicit: start with an entity, then answer using the returned draftId, revision and questionId, and follow the primary nextAction. Supported actions (skip, back, cancel, save) and the preview-then-confirm flow are given. What is missing is any when-not-to-use guidance versus the sibling drafting/creation tools.

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

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

Goes well beyond the annotations by disclosing that an encrypted undo version is saved on replacement, that the tool returns a response envelope whose primary nextAction should be followed, and that preview-then-confirm requires identical inputs. This is meaningful operational context for a destructiveHint=true, non-idempotent mutation.

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?

Front-loads the core action and the create-vs-replace default in the first two sentences, then layers the confirmation workflow. Slightly dense and partly duplicative of the schema, but no sentence is wasted.

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

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

An output schema exists, so return values need no explanation, yet the description still tells the agent to follow the primary nextAction. Combined with the undo-version and confirmation semantics, an agent has everything needed to call this destructive tool safely.

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

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

Schema coverage is 100% and the schema descriptions already explain confirm, replace, resumeId and operation in equivalent detail, so the description mostly restates structured data. It reinforces the replace/resumeId coupling but adds no syntax or edge-case detail the schema lacks – baseline 3.

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

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

States a specific verb and resource ('Import the entire resume text extracted by the chat host') plus the default outcome ('Create a NEW resume by default'). The default-new vs explicit-replace split distinguishes it clearly from siblings like update_item or restore_resume_version.

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

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

Gives explicit conditional guidance: provide resumeId, replace: true and confirm: true to replace, and use confirm: false for a preview then repeat identical inputs with confirm: true. It lacks any reference to which sibling tool to pick instead (e.g. restore_resume_version, update_item), so it stops short of naming alternatives.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new context: a per-document-type permission check and the pagination mechanism (nextCursor when another page exists). It stops short of saying what the list is scoped to (account vs workspace) or the failure mode when permission is denied.

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

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

Two sentences, zero waste, and the scoping/enumeration constraint is front-loaded before the return-value sentence. Nothing is repeated verbatim from the schema.

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

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

For a small read-only list tool with full schema coverage and an output schema, the description is nearly complete: it names the valid operations, the permission gate, and the shape of results. The only remaining gap is the scope of the underlying collection and behavior on permission failure.

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

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

Schema description coverage is 100%, so limit, cursor, detail and the operation enum are already fully documented; the description adds no syntax or format meaning beyond restating the enum choices. Baseline 3 applies when the schema does all the parameter work.

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+resource (list designs) and enumerates the three supported document types, which is more than the title conveys. Minor terminology drift between the tool name ('document templates') and description ('designs'), and no explicit separation from siblings is offered, though no sibling clearly overlaps this 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?

Usage is implied rather than stated: the agent learns it must supply one of three operations and that permission is checked for that type. There is no when-not guidance, no prerequisites about what happens if the permission check fails, and no mention of alternatives.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, yet the description prescribes a preview-then-confirm protocol, which implies a state-changing or non-idempotent action and contradicts those hints. It does add genuine value by saying the tool 'Returns the response envelope; follow the primary nextAction', but the confirm instruction actively misdescribes 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?

The opening sentences are front-loaded and dense: operation list, pagination, and the nextAction hint all land early. The final sentence about confirm: false/true consumes a quarter of the text and is both unnecessary and incorrect, so not every sentence earns its place.

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

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

An output schema exists and the description correctly points at the response envelope and primary nextAction, and annotations cover the safety profile, so most of the burden is met. What is missing is any per-operation note on which filters apply (stage/company only make sense for applications; resumeId only for ats_reports), and the erroneous confirm instruction leaves the reader with a wrong picture of the call contract.

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 and the schema already explains limit, cursor, stage, resumeId and the optional-ID omission rules. The description reinforces the ask-by-title rule for the ambiguous ID parameters, but also references a 'confirm' parameter that does not exist in a schema with additionalProperties: false, which would cause a validation failure if followed.

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

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

States a specific verb and resource ('List saved items') and immediately enumerates the eight valid operations, which lets an agent tell it apart from get_item and list_document_templates. It does not explicitly name a sibling alternative, but the resource scope 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?

The description gives real usage guidance for the human-in-the-loop case: 'Ask by title if a selection is needed' and 'do not ask the user for a cursor.' However, its main directive — 'Use confirm: false for a preview, then repeat identical inputs with confirm: true' — describes a two-step workflow the tool does not appear to require and that would break the call, so the guidance is partly misleading rather than purely helpful.

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 declare readOnlyHint=false and destructiveHint=false; the description adds real value beyond that with the no-outbound-message guarantee and the two-phase preview/confirm write pattern. The credibility of the confirm guidance is undercut because 'confirm' does not appear in the input schema, which forbids additional properties.

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

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

Four tight sentences, front-loaded with the core action and immediately followed by the safety boundary and operation list. "Returns the response envelope; follow the primary nextAction" is boilerplate-ish but brief.

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 18 parameters and an output schema present, the description needn't explain returns, and it doesn't. But for a tool this broad it gives no per-operation field guidance, and the phantom confirm parameter leaves the agent unsure whether a preview flow is actually supported.

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 18 parameters are already documented, and the description's operation list merely restates the operation enum. The one novel parameter claim — a 'confirm' flag — refers to a property absent from a schema with additionalProperties: false, adding confusion rather than meaning.

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 states a specific verb set (save/update) and resources (contacts, interactions, documents), and the operation list makes the six write modes explicit. It doesn't, however, say how it differs from siblings like create_item or update_item, which overlap on generic write semantics.

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 draws a clear negative boundary ("Never sends a message or submits an application to an employer") and prescribes the preview-then-commit flow with confirm: false / confirm: true. It stops short of naming alternative tools for adjacent jobs, so routing between log_job and create_item/update_item is left to inference.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true; the description adds real value on top by disclosing the two-phase confirm protocol, the DNS polling loop with its interval and timeout, and the need to follow the response envelope's nextAction. It does not say what a disconnect actually removes (DNS records, verification state, site data), which is the one behavioral fact a destructive operation should state.

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?

Front-loaded with the action list, then confirmation rules, then polling, then the preview/confirm mechanic — a sensible order with no filler sentences. The line "Operations: connect | refresh | status | disconnect" largely restates the first sentence, a small redundancy in an otherwise tight paragraph.

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 the hard parts of a 7-parameter, enum-driven, destructive tool: confirmation gating, polling lifecycle, nextAction handling, and preview semantics, and it correctly does not re-describe return values since an output schema exists. It stops short of stating per-operation required fields (which hostname/ID applies to which operation) or the consequences of disconnect.

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 an extra point by explaining the semantics of `confirm` as a two-step preview/commit pattern with identical inputs on the second call, which the schema does not convey. It adds nothing beyond the schema for cursor, detail, pollStartedAt or personalWebsiteId.

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?

Opens with a concrete set of verbs and a single resource ("Connect, check, refresh or disconnect a website domain") and enumerates the operation enum inline, so the agent knows exactly what capability is behind the tool. It never contrasts itself with the closest sibling, set_website_visibility, leaving that distinction to the reader.

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

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

Gives explicit routing rules: connect/disconnect require conversation confirmation, and the agent must run confirm:false as a preview, then repeat identical inputs with confirm:true. It also prescribes polling cadence (15s) and a ceiling (10 minutes). What is missing is guidance on choosing among the four operations for a given user request.

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 the mutation/safety profile generically (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the extra context here is genuinely additive: answers must be user-supplied rather than generated, the live-interview path is excluded, and the response envelope's nextAction drives the next step. No annotation is contradicted, but the phantom confirm parameter weakens confidence in the stated 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?

Three short sentences, front-loaded with the resource and operation list, then the constraints, then the confirm workflow. No filler and the most decision-relevant content comes first.

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

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

An output schema exists and the description correctly points at nextAction instead of restating return values, which is appropriate. But for a 19-parameter multi-operation tool, the description gives no per-operation parameter mapping and the one procedural instruction it does give (confirm) cannot be executed, leaving a real gap 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 per the baseline this would be a 3; however the description's only parameter-level instruction references `confirm: false` / `confirm: true`, a property absent from the schema under additionalProperties=false. Rather than adding meaning to the 19 real parameters, it introduces a name that will fail validation if used.

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+resource ('Practice written interviews') and enumerates the full operation surface (create | start | answer | finish | review | status), so an agent knows exactly what the tool covers. It also draws a scope boundary against sibling behavior by noting that live interviews live in the dashboard, not here.

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

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

Gives clear workflow sequencing guidance ('Returns the response envelope; follow the primary nextAction'), a hard constraint ('Answers must come from the user'), and a preview-then-confirm protocol. The guidance is strong but is undercut by instructing a `confirm` field that does not exist in the schema, which could steer the agent into an invalid call.

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 annotations already declare this is a non-read-only, destructive, non-idempotent mutation, and the description adds a concrete preview-then-confirm workflow: preview with confirm: false, describe the effect, ask the user, then repeat identical inputs with confirm: true. It also discloses the return shape with links and nextActions.

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 purpose and usage, then follows with return and preview guidance. It is mostly efficient, though the return-value sentence is somewhat redundant because an output schema exists.

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 a single required parameter, full schema coverage, rich annotations, and an output schema, the description covers purpose, confirmation safety protocol, preview behavior, and return expectations. An agent has everything needed 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?

Schema coverage is 100%, so the confirm parameter is already fully documented, establishing a baseline of 3. The description adds workflow meaning by explaining that the exact same inputs should be repeated after previewing with confirm: false and obtaining user confirmation.

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: 'Restart your paused annual career pass', with the resumability condition. It clearly distinguishes reactivation from generic pass management, so an agent can identify the operation without opening the schema.

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

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

It gives explicit timing and confirmation requirements: use it after the user asks to restart and confirms with confirm: true, and preview with confirm: false first. It does not explicitly name any sibling alternative such as get_pass_pause_preview, so sibling routing remains slightly implicit.

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

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

Adds real value beyond the annotations by disclosing allowance consumption, the confirmation gate, and polling/timeout behavior. However, annotations flag destructiveHint=true and openWorldHint=true, and the description never explains what is destroyed or that results come from external sources; it also omits the 24-hour idempotency replay window that the schema only implies.

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?

Five sentences, front-loaded with purpose, then constraint, then cadence, then operations and return contract. Dense but nearly every clause carries operational information; the polling sentence is the only one that could be tightened.

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 17-parameter, five-operation stateful tool, the description covers the confirmation and polling mechanics well and an output schema exists to cover returns. But it never maps which parameters belong to which operation, nor what select or refresh actually change, leaving gaps an agent must guess at.

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 baseline is 3. The description adds one genuinely useful piece of semantics — reusing identical inputs with confirm:true after a preview — but leaves the operation-specific field groupings (jobId vs researchId vs candidateIndex vs sectionIds) unexplained despite the schema's terse generic parameter text.

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?

Opens with a specific verb and resource ("Research a company from its real name and website") and enumerates the five operations, so the agent knows the tool is a stateful research workflow rather than a one-shot lookup. No sibling overlaps, so no discrimination is needed, but the description never states what a finished research result contains.

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

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

Gives concrete procedural guidance: which operations need conversational confirmation, the confirm:false preview then confirm:true pattern, and a 5-second poll for up to 10 minutes. It does not explain when to choose select vs refresh vs create, leaving operation selection largely to the caller.

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 annotations flag destructiveHint=true and idempotentHint=false, but the description adds behavior they cannot express: the current content is saved as another undo version, so the change is reversible, and a preview pass must precede the confirmed write. It also states the return payload, which matters for chaining.

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

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

Four short sentences, front-loaded with what the tool does, then the workflow constraint, then the side effect. No filler and nothing repeated from the schema verbatim.

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

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

An output schema exists so return values needn't be spelled out, and the description still covers the confirm workflow and the undo-version side effect. The minor gap is that it does not state explicitly that the preview step means calling with confirm: false, leaving that to 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% and each param already has a description, so the baseline is 3. The description still adds meaning: it clarifies that confirm must be set only on the second call after explicit user confirmation, and that resumeId/versionId come from prior import or restore responses.

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

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

States a specific verb and resource plus the scope: restoring resume content saved before an import. Clear enough that an agent can distinguish it from import_resume_text, but it never names a sibling or explicitly contrasts with them, which is what a 5 requires.

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

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

Gives an explicit two-step operating procedure (preview first, then repeat identical inputs with confirm: true only after explicit conversation confirmation). Strong context, but it names no alternative tool and gives no 'when not to use' exclusion.

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

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

The annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=true, and idempotentHint=true. The description adds meaningful behavioral context beyond those annotations: both changes require conversation confirmation, confirm:false is a preview, confirm:true repeats identical inputs, and the caller should follow the response envelope's primary nextAction.

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 short and front-loads the core action. Most sentences earn their place by covering the confirmation workflow and preview behavior; 'Operations: set' is slightly redundant with the schema enum, but overall the structure is efficient.

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, open-world website visibility mutation with full schema coverage and an output schema, the description is complete enough to call correctly. It covers purpose, confirmation requirements, preview workflow, and how to follow the response, while the schema handles parameter-level details.

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. The description adds useful meaning beyond the schema by explaining the confirm:false preview followed by confirm:true with identical inputs, which clarifies how the confirm parameter should be used in practice.

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

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

The description gives a clear verb and resource: 'Publish a website or take it offline.' This is more specific than the title and distinguishes the action from generic sibling tools like manage_website_domain, but it does not explicitly name or differentiate against those siblings.

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

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

The usage context is implied by the publish/offline action, and the description adds a confirmation workflow with preview mode. However, it does not explicitly say when to use this tool versus alternatives such as manage_website_domain, nor does it state exclusions or prerequisites.

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 that the result is a short overview focused on strengths, but it does not provide meaningful extra behavioral context such as limits or handling of empty resumes.

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 short and front-loaded, with the purpose first and usage guidance second. The return-value sentence slightly overlaps the opening 'short overview' phrasing and is somewhat redundant because an output schema exists.

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 low complexity, full parameter schema coverage, annotations, and an output schema, the description provides everything needed to call it correctly. The agent knows the purpose, when to use it, and the general shape of the result.

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 single optional resumeId parameter is fully documented in the schema, including the behavior when omitted. The description adds no parameter-specific meaning beyond what the schema already provides, which is appropriate for 100% schema description coverage.

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 action on a specific resource: give a short overview of a saved resume. This is clear enough for an agent to know what the tool does, but it does not differentiate from nearby siblings such as check_resume or get_resume_statistics.

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 use it when the user wants to understand a resume's main strengths before making changes. That is a clear usage context, though it does not mention when not to use it or name an alternative tool.

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

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

Annotations already flag destructiveHint=true, idempotentHint=true and readOnlyHint=false, and the description adds genuinely new behavioral context: a mandatory consent-confirmation rule and a two-phase preview/commit protocol, plus a pointer to nextAction in the response envelope. It doesn't say what a rejected or partial mutation looks like, but the confirmation semantics are a real value-add beyond 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?

Three tight sentences, front-loaded with the purpose, then the operation list, then the confirmation protocol. The inline pipe-delimited operations list costs almost nothing and keeps the whole definition scannable.

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 11 parameters, seven operations, a nested consents object and an output schema, the description covers the workflow but not the field-to-operation mapping, which is the main way an agent can go wrong here. It also doesn't note that the 'view' operation is a read inside an otherwise destructive tool.

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 every parameter carries its own description, so the schema carries the load and baseline 3 applies. The description adds the confirm preview/commit meaning, but it never maps which fields belong to which operation, leaving the critical 'each operation accepts only its own fields' constraint to 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?

States a specific verb and resource (change profile or account preference) and enumerates all seven operations, so an agent knows exactly what surface this covers. It doesn't explicitly distinguish itself from mutation siblings like update_item, but the account-scoped framing is clear enough.

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

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

Gives concrete procedural guidance: consent changes require conversational confirmation, and mutations follow a preview (confirm: false) then repeat-with-confirm: true pattern. It stops short of per-operation when-to-use notes or when to prefer a sibling tool, which keeps it below a 5.

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

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

Annotations already declare destructive=true, readOnly=false, idempotent=false, so the safety profile is structured. The description adds important behavioral context: confirmation requirements for generated replacements, the preview/confirm workflow, and the instruction to follow the response envelope's primary nextAction. It does not enumerate the specific destructive effect of each operation, which keeps it from a 5.

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

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

The description is front-loaded with purpose and confirmation guidance, then operation scope, then return/envelope behavior. The long operation list duplicates the schema enum, which is somewhat redundant, but it also communicates the tool's breadth in one place. Overall it is appropriately sized for a 19-operation umbrella 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?

Given 50 parameters, nested objects, an output schema, and destructive annotations, the description covers the critical context: operation scope, confirmation workflow, contracts resource, guided_turn fallback, and response envelope handling. It is not a full operation-by-operation guide, but the schema and output schema carry the detailed contract and the description fills the high-level gaps.

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 all 50 parameters and a baseline of 3 applies. The description meaningfully adds beyond the schema by explaining the contracts resource for typed paths/values, the guided_turn fallback for missing facts, and the confirm:false-then-confirm:true preview pattern. It does not explain individual parameters, but it adds useful semantics for the highest-risk fields.

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: editing a saved document or application via a selected operation. It lists all operation families, making it clear that this is an umbrella edit tool rather than a create/delete tool. It does not explicitly contrast with siblings like create_item or delete_items, so it falls short of a 5.

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

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

It gives concrete usage guidance: use confirm:false for preview, then repeat with confirm:true after user confirmation; generated replacements require conversation confirmation; document field edits should read democruit://contracts/{memberTool} or use guided_turn. It lacks explicit when-not-use guidance and does not route between all sibling edit/alternative tools, but the context is clear.

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