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

Beyond the readOnlyHint annotation, the description discloses significant internal behavior: it makes two API calls, how it passes a context parameter, and how it handles questionnaires exceeding a size ceiling (returns size and top-level keys, with raw view as a workaround). This is exceptionally transparent and adds value beyond the annotation.

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 dense but well-structured, front-loading the purpose and then adding credential requirements, default behavior, and edge cases. Each sentence contributes necessary information given the tool's complexity, though it is slightly longer than minimal.

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

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

With no output schema, the description covers the return value at a high level (pages, questions, answers) and explains the ceiling case. It also explains the two-call process and credential needs. The tool is simple to invoke (0 required params), and the description is sufficient for correct usage.

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 both parameters are already well documented. The description adds only marginal detail (e.g., the ceiling behavior for view='raw' is already in the schema). It does not substantially enhance parameter understanding beyond the schema, so the baseline 3 is appropriate.

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

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

The description clearly states the tool reads a HoneyBook questionnaire, listing its content (pages, questions, answers). It distinguishes itself by the credential type (flow credential vs client-portal session), but does not explicitly name a sibling tool, so it earns a 4 rather than 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 description provides explicit guidance on when to use the tool: requires a flow credential and explicitly notes a client-portal session will NOT work. It also explains the default behavior (most recently captured flow) and suggests using list_active_sessions for flow ids, giving clear context without naming an alternative tool directly.

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

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

Annotations already provide readOnlyHint=true, so the safety profile is covered. The description adds some behavioral context beyond the annotation (default body format is plain text, full-read scope including attachments and delivery status), but does not address edge behaviors such as error handling for missing messages or session/auth requirements.

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

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

A single, front-loaded sentence with zero filler. The primary verb-resource pair leads, and the content enumeration is compact yet complete.

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 read-only tool with readOnlyHint and a fully described schema, the description covers the return contents well, which matters because there is no output schema. The main gap is that it never clarifies whether reading marks the message as seen, which is a live ambiguity given the sibling mark_messages_seen.

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 only marginal parameter meaning, confirming the 'text' default for format (already stated in the schema). It does not need to compensate for schema gaps since the schema's parameter descriptions are already thorough.

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 ('Read one message in full') and enumerates the contents (body, sender, recipients, attachments, per-recipient delivery status). 'One message in full' inherently contrasts with sibling list_messages, so an agent can distinguish them at a glance.

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

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

No when-to-use, when-not-to-use, or alternative routing is provided. The description implies usage through its purpose but never says to use list_messages to obtain the ID first, nor clarifies when send_message or mark_messages_seen would be the right choice instead.

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 readOnlyHint annotation, the description warns that view='raw' returns a large untrimmed response embedding the vendor's account, and that compact drops fields. This is useful behavioral context for an agent deciding between views.

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 with no filler; purpose is front-loaded, and the raw-view caveat is placed second. The field list is long but each entry is concrete and relevant.

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 read-only getter with all parameters documented in the schema and no output schema, the description covers what is returned and the two view shapes. Minor gaps like origin resolution are already handled by 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 description coverage is 100%, so the baseline is 3. The description adds only a minor extra warning that raw is large; it doesn't materially improve on the schema's 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?

Description clearly identifies the resource: the portal's Overview 'Project details' card plus participants, enumerating fields. It doesn't explicitly contrast with sibling tools like list_projects or get_flow, but the resource is specific enough to avoid ambiguity.

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?

Purpose implies use when project details are needed, and the view parameter gives shape options. However, there is no explicit when-to-use vs alternatives, no exclusions, and no mention that project_id should come from list_projects (only the schema says this).

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, so the safety profile is covered. The description adds that the result includes status flags such as has_sent_files, has_signed_files, has_paid_payments, which is useful output context, but it doesn't disclose error behavior or other response characteristics.

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?

One concise, front-loaded sentence that states the action and key output in an efficient way. No filler or redundancy.

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

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

For a read-only getter with a required ID and no output schema, the description gives enough orientation: it promises full detail and names representative status flags. It could be slightly richer about what 'full detail' includes, but the schema already supplies the parameter context.

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?

Input schema covers all parameters (workspace_id, origin) with descriptions, so the baseline is 3. The description adds no extra parameter semantics beyond mentioning status flags, which relate to the response rather than 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 uses a specific verb ('Get') and identifies the resource ('workspace (vendor project)') with a concrete output detail ('status flags'). It is clear what the tool returns, though it does not explicitly distinguish it from siblings like get_project or get_workspace_file.

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

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

No guidance on when to use this tool versus alternatives; the intended trigger or context is only implied by the name and required workspace_id. There are no exclusions or sibling comparisons.

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, so the description doesn't need to restate that. It adds valuable behavioral context: the default summary fields, the effect of each section value, and the caveat that 'raw' may exceed MCP size limits on proposal-class files. This goes beyond annotations and helps agents anticipate response size and content.

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

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

The description is two sentences, front-loaded with the primary purpose, then providing concise but essential detail on the section parameter. It avoids unnecessary fluff and is well-organized, though it could be slightly more compact by trimming redundant phrasing.

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 (one enum with six options) and absence of an output schema, the description does a good job covering the main behavior: default summary contents, section meanings, and size warning for raw. It doesn't cover error conditions or authentication, but those are covered by the read-only annotation and the optional origin parameter context. Overall, sufficient for an agent to call it correctly.

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

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

Schema coverage is 100%, so all parameters are documented in the schema. The description adds significant semantics for the section parameter by explaining each enum value (pricing, agreement, payments, all, raw) and what they return. It also clarifies the default summary contents. For file_id and origin, the schema already provides adequate descriptions, so no extra value 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 tool's function: 'Get detail for one workspace file.' It specifies the resource (workspace file) and the action (get detail), and differentiates from siblings by indicating this is for a single file while list_workspace_files handles listing. The default summary and section options further clarify scope.

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

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

The description implicitly guides when to use the tool—when you need detail on a single file—and explains how to use the section parameter to drill into specific parts. It doesn't explicitly name alternatives, but the context of sibling tools (list_workspace_files, get_workspace) makes the distinction clear. It also warns about raw responses exceeding size limits, aiding safe usage.

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 mark it read-only and idempotent, and the description adds substantial behavior beyond that: it makes exactly one authenticated request, reports the credential source and acceptance, never returns the credential, and distinguishes failure categories. This goes well beyond the annotation hints and avoids any contradiction.

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

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

Four sentences, each carrying distinct information: what action is performed, what is reported, read-only/credential safety, and when to call it. There is no filler, repetition, or schema duplication.

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

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

With no parameters, no output schema, and no nested objects, the description carries the full burden of explaining the tool. It covers purpose, behavior, output contents, safety properties, and invocation timing. Nothing an agent needs to correctly invoke and interpret this tool 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 tool has zero parameters, with schema coverage at 100%, so the baseline is 4. The description adds no parameter-level detail because none is needed, but it does explain what the tool does with its implicit credential input, which is contextually relevant.

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 names a specific verb ('resolves', 'makes', 'reports') and a concrete resource (api.honeybook.com), and clearly frames the tool as a credential/upstream healthcheck. This distinguishes it from all sibling tools, which are operational actions like list_messages or pay_invoice.

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

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

The description gives explicit guidance: 'Call this when a real tool fails and you want to know which hop broke.' This clearly tells an agent when to use it, though it does not enumerate exclusions or name alternative diagnostic tools if any exist.

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 readOnlyHint annotation, the description adds key behavioral context: 'No API call' indicates this is a local operation with no external side effects. It also discloses the access scopes of each credential kind (e.g., portalSessions read workspaces/files/invoices, flowCredentials are weak auth scoped to a single questionnaire). This goes well beyond what annotations alone 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?

Two sentences, each earning its place. The first sentence states the purpose and the split; the second explains the provenance and the non-interchangeability. There is no filler or repetition of schema or annotation data. The off-putting but necessary 'No API call' is placed at the end, after the more important distinctions.

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 identifies the exact credential types, how they are captured, and their access capabilities. It also differentiates from sibling tools without needing to enumerate those tools. Given its simplicity and the richness of the description, nothing essential is missing.

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

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

The tool has zero parameters, and schema coverage is trivially 100%. The description compensates by clarifying what the output represents: active credentials split by kind with their derivation and limits. Since no parameters exist, the description fully satisfies any parameter-semantics needs and adds meaningful detail about the result domain.

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: 'List the HoneyBook credentials currently active in this MCP.' It further details the two kinds of credentials and the tools that capture them, which clearly distinguishes this from sibling listing tools. The presence of sibling names like list_projects and list_notes reinforces that this tool is specifically about credential inventory, not general data listing.

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 guidance on what the two credential types are and when they are created (use_magic_link vs use_flow_link), with a warning that they are not interchangeable. This implies when to use the tool—to inspect current active credentials and their capabilities. It lacks an explicit 'use this when' statement but the context is effectively informative.

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?

readOnlyHint=true already covers the safety profile, and the description adds useful scoping context about what is included and excluded. It adds no operational detail such as pagination or return shape, but for a read-only list tool the annotation carries the main behavioral burden.

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?

A single dense sentence that front-loads the resource and immediately provides the disambiguating exclusion. Every word earns its place 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 simple two-parameter read-only list tool, the description plus schema provide everything needed to select and invoke it correctly. The lack of an output schema means return-shape details are absent, but they are not essential for correct invocation.

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

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

Schema coverage is 100%, with workspace_id and origin already documented including origin's optionality and workspace_id's source. The description adds no parameter-level meaning, so the baseline 3 is appropriate.

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

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

The description states a specific verb and resource: listing loose images, files, and bookmarks in a workspace. It also explicitly differentiates itself from list_workspace_files by scope, so an agent can tell the two apart immediately.

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 names the sibling tool list_workspace_files and clarifies the boundary by saying contracts/invoices/proposals belong there. It does not literally say 'use this when...', but the exclusion makes the intended context clear.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavior beyond that: meetings are 'derived from the workspace feed', rescheduled meetings show the latest time, and results are sorted by start. This gives an agent useful expectations about data freshness and ordering.

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 sentences deliver the core purpose upfront, followed by relevant behavioral caveats and sorting. Each clause carries information, and there is no filler or repetition.

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

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

For a simple read-only list tool, the description is complete: it lists the output fields, notes the data source, explains update behavior, and the schema covers all parameters. Minor gaps like pagination are absent, but they are not essential for a basic list 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?

The schema fully documents both parameters (workspace_id and origin) at 100% coverage, so the description does not need to add parameter detail. The description adds no extra semantic value about parameters, aligning with the baseline of 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?

The description identifies a specific verb ('list'), a distinct resource ('meetings'), and a clear scope ('in a workspace'), and enumerates the returned fields. It also gives concrete meeting types as examples, making it unambiguous what the tool retrieves.

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

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

The description implies when to use it: when you need vendor-scheduled meetings in a workspace, with fields like title, times, join link, and password. However, it does not explicitly state exclusions or alternatives, such as what to use for unscheduled meetings or how this differs from listing other resources.

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, and the description adds behavioral detail beyond that: it explicitly states that reading does NOT mark anything as seen, which is a critical side-effect guarantee. It also describes the return format (compact cards, newest first) and ordering. This goes beyond the annotation's basic read-only flag, providing agent-relevant behavioral transparency.

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

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

The description is two sentences with no redundancy. The main purpose is front-loaded, followed by return format details and the key behavioral note about not marking as seen. Every sentence earns its place, and the structure is clean and 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?

Given the tool's moderate complexity (4 parameters, all documented, no output schema), the description covers the essential return format (compact cards with sender, subject, preview, seen state, attachments) and mentions the alternative get_message. It doesn't cover pagination behavior or error conditions, but the limit parameter is documented in the schema and the tool is a straightforward listing operation. It is nearly complete for its purpose.

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%: every parameter (kind, limit, origin, workspace_id) has a detailed description including enums and defaults. The description adds minimal extra semantic value beyond the schema, only hinting at the 'activity log' option via the phrase 'optionally the activity log'. With full schema coverage, 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 description clearly identifies the tool as listing messages and optionally the activity log in a workspace, referencing the portal's Activity tab. It distinguishes from get_message (full body) and implies a read-only listing operation. The verb 'list' + resource 'messages/activity' + scope 'workspace' is specific and unambiguous, differentiating it from siblings like send_message or mark_messages_seen.

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 context: it returns compact cards newest first and explicitly points to get_message for full body as an alternative. It also notes that reading does NOT mark anything as seen, which helps avoid confusion with mark_messages_seen. However, it doesn't explicitly state when not to use this tool (e.g., for sending messages) or exhaustively list alternatives, so it's slightly 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?

The readOnlyHint annotation already establishes the safe read-only nature. The description adds useful context by indicating only vendor-shared notes in a workspace are returned and giving examples like meeting notes and AI recaps. It does not disclose ordering, pagination, or edge cases, but the annotation lowers the burden.

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 a single, front-loaded sentence with no wasted words. It states the resource, scope, content examples, and portal mapping without repeating schema details or annotations.

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 read-only list tool with full parameter descriptions and a readOnlyHint, the description is mostly complete: it explains what kind of notes are returned and where they appear. It could mention return shape or more explicit list behavior, but the low complexity and supported schema make this a minor gap.

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

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

Schema description coverage is 100%, so the schema already documents workspace_id and origin. The description's mention of 'in a workspace' loosely aligns with workspace_id, but it does not add parameter-level meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description identifies the resource and scope: notes the vendor has shared with you in a workspace, pointing to the portal's Notes tab. It is not a tautology and distinguishes the tool from siblings like list_messages or list_attachments by content type, though it lacks an explicit verb such as 'lists' or 'retrieves.'

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?

There is no guidance on when to use this tool versus alternatives such as list_messages, list_meetings, or list_attachments. It implies the intended context through 'in a workspace' and 'Notes tab,' but never states exclusions or conditions that would help an agent choose it over similar list 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?

The readOnlyHint annotation already signals a safe read operation, and the description adds a useful behavioral detail: 'Empty array if none are saved.' Beyond that, it does not disclose return format, authentication requirements, or vendor-context behavior, but the annotation lowers the burden.

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 one concise sentence that states the action and resource, plus a useful edge-case note about the empty array. There is no filler or redundancy.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description covers the essential semantics and one important return behavior. It could mention what the array contains, but the overall context is sufficiently 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?

Schema description coverage is 100% for the single optional 'origin' parameter, and the schema already explains its purpose. The description adds no parameter-specific detail, so the baseline score 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 description uses a clear verb and resource: 'List saved payment methods for your client account with a vendor.' It also distinguishes itself from the sibling list_payments by specifying 'saved payment methods' rather than payments or transactions, so an agent can identify this tool's scope.

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

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

The description does not state when to use this tool versus alternatives like list_payments, nor does it mention exclusions or prerequisites. The purpose is clear, but no explicit guidance is given for choosing among related 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?

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral detail about the return contents, including totals per currency and invoice-number reporting. It implies no side effects or destructive behavior. It does not discuss pagination or ordering, but these are minor for a simple read-only list.

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

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

The description is two sentences with no wasted words: purpose is front-loaded, return fields are listed compactly, and the alternative action is routed in a single final clause. It avoids repeating schema or annotation information.

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

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

For a simple read-only list with no output schema, the description conveys the key return data an agent needs, plus the relevant sibling action. The response shape is predictable from the described fields, and nothing essential is missing for selecting and invoking 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 description coverage is 100%, with workspace_id and origin already fully described in the input schema. The description only reiterates the workspace scope and adds no parameter-level semantics beyond what the schema provides, so the high-coverage baseline of 3 applies.

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

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

The description clearly identifies the resource as 'Payment schedule for a workspace' and specifies the returned content: per-file amount, due date, paid/pending state, payment method, invoice number, and paid/unpaid totals per currency. It also distinguishes itself from the sibling pay_invoice by explicitly directing the agent there for payment actions.

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 establishes that this is the Payments-tab listing and gives an explicit routing rule: 'To pay one, use pay_invoice.' It does not compare itself with list_payment_methods or state exclusions, but the read-versus-pay alternative is clear enough for correct 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?

The readOnlyHint annotation already covers the safety profile. The description adds useful context about the vendor/portal scope and the workspace_id's cross-tool importance, but does not go further into pagination behavior, result limits, or multi-session edge cases.

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

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

Two compact sentences deliver the core purpose, the key output field, and the mental model ('project switcher') with no redundant wording. Information is front-loaded and every clause 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?

The tool is simple, has no required parameters, and is marked read-only. The description covers what the tool lists, the returned fields, and why the workspace_id matters. The input schema covers both parameters, so nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so page and origin are already fully documented. The description does not repeat parameter details, which is fine; it adds value by clarifying what the tool returns rather than how inputs behave.

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

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

The description clearly identifies the action ('List'), the resource ('your projects'), and the vendor-specific naming ('HoneyBook calls them events'). It also enumerates the returned fields, making it easy to distinguish from sibling tools like get_project.

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

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

The description gives a strong usage cue by stating that it returns workspace_id 'that every other workspace tool takes' and calling it 'the portal's project switcher.' This implies when to use it, though it does not explicitly name alternatives or exclusion conditions.

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 readOnlyHint=true, the safety profile is already covered. The description adds useful behavioral detail: it returns today/this week/overdue/completed counts, any task groups, and sorts by due date. This is beyond what the annotation declares.

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?

A single sentence captures scope, output composition, and sort order with no filler. It is front-loaded with the resource and follows with the distinguishing views.

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 read-only list tool, the description conveys what is returned (tasks, counts, groups, sorting) and scopes it to a workspace. Pagination and date-bucketing are left to the schema, which fully documents them, 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?

The input schema covers all 5 parameters with descriptions, so the baseline is 3. The tool description mentions 'workspace' context and due-date sorting but doesn't add meaning beyond what the schema properties 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 identifies the resource as vendor-assigned tasks within a workspace and references the portal's Tasks tab, making it distinct from sibling list tools. It doesn't state an explicit verb ('list'), but the resource and scope are 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?

There is no explicit when-to-use guidance or mention of alternatives among siblings. The context ('the portal's Tasks tab', vendor-assigned tasks) implies when it applies, but no exclusions or cross-references are 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?

readOnlyHint=true already conveys that this is a safe read operation; the description adds useful scoping context ('vendor has shared', file type categories) but does not disclose pagination, sorting, or the shape of the returned file list. Since there is no output schema, those details are not available elsewhere.

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?

One sentence with no filler; the parenthetical examples (contracts, invoices, brochures, proposals) quickly communicate the tool's domain. The main purpose is front-loaded and every element earns its place.

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

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

For a read-only list tool with two optional parameters, zero required parameters, and a fully documented schema, the description is sufficiently complete for an agent to invoke it correctly. It could be stronger by noting how it differs from get_workspace_file, but that is a minor gap for such a simple 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 description coverage is 100%, so both origin and file_type are already documented structurally. The description only paraphrases the file_type filter ('Optionally filter by file_type') without adding new meaning beyond the schema.

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

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

The description states a specific verb and resource ('List all files a vendor has shared with you') and gives concrete file type examples arena. It reads as a clear list-all operation, but it does not explicitly distinguish itself from the sibling get_workspace_file or clarify when that singular tool should be used instead.

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 no guidance about when to choose this tool over alternatives like get_workspace_file or list_attachments. The 'Optionally filter by file_type' clause is parameter usage rather than usage selection guidance, leaving the agent to infer 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.

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

Annotations already signal mutation (readOnlyHint=false), idempotence, and non-destructiveness. The description adds useful behavioral context by clarifying that read-only listing/fetching tools do not trigger the seen side effect, and by giving the real-world portal analogy. There is no contradiction with annotations.

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

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

Two short sentences convey the action, the behavioral context, and the sibling distinction with no wasted words. The core action is front-loaded before the explanatory analogy.

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 simple, annotations cover safety and idempotence, and schema covers all parameters. The description gives enough context to select and invoke it correctly, though it does not describe return values or error behavior; this is minor for a low-complexity mutation tool with no output schema.

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

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

Schema description coverage is 100%, so the parameters are already well documented in the schema, including where to obtain workspace_id and message_ids. The description itself adds no parameter-level meaning beyond the schema, which fits the baseline for high schema 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?

The description uses a specific verb and resource ('Mark feed items as seen') and immediately differentiates from siblings by stating that list_messages and get_message never do this on their own. It is clear what the tool does and how it differs from related read 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?

The description explains the portal's Activity tab behavior and explicitly warns that list_messages and get_message do not mark items as seen, which helps an agent know when this side effect is needed. It does not name an alternative tool to use instead, but the context is sufficient for 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?

The description discloses important behavior not in annotations: that v1 returns a deep link instead of doing headless payment, and that confirm=true is required. This is valuable. However, annotations already include destructiveHint=true, and the description does not elaborate on the destructive nature (e.g., irreversible charge, need for user confirmation beyond the confirm flag). No contradiction found.

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

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

The description is two sentences packed with critical details: purpose, v1 limitation, and a usage requirement. No fluff. Front-loaded with the verb and resource. Ideal for quick scanning.

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 (3 params, 1 required), the description covers the essential behavior (deep link return, confirm requirement) and the source for file_id. It lacks an explicit note on what the preview looks like or error conditions, but that might be acceptable with the confirm hint. Slight omission: doesn't mention prerequisites like having an active session, but that may be implied by the origin param.

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%, meaning all parameters are described in the schema. The description adds context for 'file_id' (from list_workspace_files with file_type=invoice) and 'confirm' (must be true to avoid preview), which enriches semantics. But it does not add significant detail to 'origin' beyond schema. Baseline 3 is appropriate given high 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?

The description clearly states the tool's purpose: to pay an invoice from a vendor. It also notes the v1 behavior of returning a deep link rather than headless payment, which is a specific and useful detail. However, it does not explicitly differentiate from other payment-related siblings like 'list_payments' or 'list_payment_methods', which could be a minor distinction.

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

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

The description implies usage through the example (pay an invoice) and the mention of 'confirm:true', but it does not explicitly state when to use this tool versus alternatives, such as 'list_payments' for viewing payments or 'sign_contract' for contracts. It lacks a clear 'when not to use' or reference to sibling 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds valuable behavioral context: that HoneyBook emails every recipient, that confirm:true is required to actually send (implying a dry-run without it), and that replies inherit the subject. This goes beyond the annotation flags and helps the agent understand side effects and the confirmation guard.

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

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

The description is two sentences with zero fluff. It front-loads the core action and then adds the most important operational detail (confirm:true) and reply mechanism. Every sentence earns its place.

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

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

For a tool with 6 parameters and 100% schema coverage, the description covers the critical behavioral aspects: the email side-effect, the confirmation requirement, and reply semantics. It does not describe the return value, but since no output schema exists and the confirm parameter's preview behavior is already in the schema, this is a minor gap. The description is sufficient for an agent to call the 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 description coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining the reply behavior ('Pass reply_to_message_id to reply in-thread (the subject is inherited)') and clarifying the confirm requirement ('Requires confirm:true'), which enriches the agent's understanding beyond the schema's 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 states a specific verb ('Send'), a specific resource ('message to the vendor and other workspace members'), and the mechanism ('through the HoneyBook portal, exactly as the Activity tab composer does'). It clearly differentiates from sibling tools by being the only messaging tool; the reply functionality is also explicitly mentioned.

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

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

The description gives clear context on when to use the tool (to message the vendor and workspace) and how to use it (pass reply_to_message_id for replies, confirm:true to send). It does not explicitly list alternatives or exclusions, but no competing messaging sibling exists, so the guidance is adequate.

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 only destructiveHint=true in annotations, the description carries the burden of explaining non-obvious behavior: it explicitly discloses that v1 returns a deep link to the HoneyBook portal rather than completing a headless signature. It also reinforces the confirmation requirement, matching the schema's 'must be true to proceed'.

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 short sentences with the purpose front-loaded and the key v1 caveat immediately after. Every clause contributes to understanding the tool; the confirm sentence is slightly redundant with the schema but remains valuable as an explicit requirement.

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 3-parameter mutation with no output schema, the description covers the essential return behavior (deep link), the confirmation requirement, and the vendor-contract use case. It could say more about how to handle the returned portal link, but the schema already documents origin and file_id.

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?

All three parameters (origin, confirm, file_id) have full schema descriptions, so the baseline is 3. The description only restates the confirm requirement and does not add selection, formatting, or fallback guidance beyond what the schema already provides.

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

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

The description names the exact action ('Sign a contract'), identifies the object and source ('contract you received from a vendor'), and immediately clarifies the v1 behavior ('returns a deep link ... instead of signing headlessly'). This makes it clearly distinguishable from the read/list/auth siblings such as use_magic_link and list_workspace_files.

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 states the target scenario ('contract you received from a vendor') and the mandatory guardrail ('Requires confirm:true'). It does not enumerate alternatives or explicit when-not conditions, but for a single-purpose signing tool 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.

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

Annotations only provide readOnlyHint=false, so the description carries the full burden. It discloses that the tool snapshots localStorage into a file, explains the credential's scope limitations (cannot read portal workspaces, files, etc.), and mentions the re-approval requirement per flow. This is rich, accurate behavioral context with no contradiction.

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

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

A single, well-organized paragraph front-loads purpose and usage, then covers prerequisites, behavior, and limitations. Every sentence adds new information without redundancy or 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 one-parameter tool with no output schema, the description covers all essential context: when to use, prerequisites, exact behavior, storage location, scope limits, and parameter guidance. Nothing an agent needs to decide or execute 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% but the description adds significant nuance: it clarifies that only the /flow/<flowId> segment is required, that the rewritten step URL works, and explains the fallback use of ?hash=. This goes well beyond the schema's basic format hint.

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 ('Capture') and resource ('HoneyBook QUESTIONNAIRE (flow) credential'), and immediately distinguishes from a sibling tool (`use_magic_link`). The link shape is explicitly defined, making the tool's purpose unmistakable.

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 states exactly when to use this tool (for /flow/ links) and when not (for /app/link/resolve/ links), naming the alternative tool. It also lists prerequisites (install extension, open link, let render) and a clear workflow.

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 reveals key behaviors: it reads localStorage['HONEYBOOK_REACT_CURR_USER'], writes to ~/.honeybook-mcp/sessions.json, does not sniff live requests, derives only the portalOrigin from the argument, and refuses questionnaire links. This is rich, non-obvious behavior that an agent must know before calling the tool.

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 longer than average, but every sentence carries useful operational information: prerequisites, mechanics, parameter semantics, behavior, and sibling routing. It is front-loaded with the core purpose and remains dense rather than redundant, though it could be tightened slightly.

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 one parameter, notable prerequisites, side effects, and no output schema, the description covers everything needed to call it correctly: setup steps, parameter meaning, session persistence, default session selection, and the alternative tool path. Nothing essential is missing.

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

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

The schema already documents magic_link_url thoroughly at 100% coverage, so the baseline is 3. The description adds meaningful nuance beyond the schema: the URL is used only to derive a cache key/origin and is never opened or navigated to, saving the agent from a plausible misunderstanding.

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: 'Capture a HoneyBook client-portal session via the fetchproxy 0.3.0 browser extension.' It also differentiates from the sibling use_flow_link by explicitly warning that questionnaire links require the sibling tool and that this tool refuses them.

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

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

The description gives explicit prerequisites (install fetchproxy, open and sign in to the magic-link URL, leave the tab open), clarifies the tool does not open or navigate to the URL, and names the exact alternative tool for questionnaire links. This leaves no ambiguity about when and how to invoke it.

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