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

Annotations declare readOnlyHint=true, aligning with the description's 'Get' action. The description adds value by specifying that the response includes status flags, providing behavioral context beyond the annotation's safety profile. No contradictions.

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

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

The description is very concise, consisting of two sentences that convey the purpose and added value (status flags). Every word earns its place with no unnecessary content.

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

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

Given the absence of an output schema, the description partially covers return values by listing some status flags, but does not provide a complete picture of all fields returned. Lacks guidance on when to use relative to siblings, which are diverse.

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 does not add extra meaning to the parameters beyond what the schema provides (workspace_id and origin are clear). The mention of status flags relates to output, not 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 clearly states the verb 'Get' and the resource 'workspace (vendor project)', and specifies that it returns full detail including status flags like has_sent_files, has_signed_files, has_paid_payments. This differentiates it from siblings such as get_workspace_file or 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?

No explicit guidance on when to use this tool versus alternatives like list_workspace_files or pay_invoice. The context suggests it's for retrieving a single workspace's details, but no when-to-use or when-not-to-use instructions 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?

The description discloses that raw may exceed MCP size limits, provides size estimates for summary, and details what each section returns. This adds value beyond the readOnlyHint 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?

Two sentences with no wasted words. Front-loaded with purpose and defaults, then describes optional drill-down. Perfectly concise.

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 3 parameters, no output schema, and enums, the description is very complete: default behavior, section options, size warning, and source of file_id. 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?

Schema coverage is 100%, and the description adds significant meaning: file_id origin, and section values explained with examples ('pricing' for full line items, etc.). This helps the agent choose correctly.

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 'Get detail for one workspace file' and explains the default vs. drill-down behavior. It distinguishes from siblings like list_workspace_files (which lists files) and other workspace-related 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 explicitly tells when to use each section parameter value, but does not explicitly state when not to use this tool (e.g., if just listing is needed). However, the context is clear enough for an agent to infer.

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

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

Annotations indicate readOnlyHint=true, and the description adds that no API call is made, which is useful. No further behavioral traits (e.g., rate limits, scope) are 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?

Two concise sentences, front-loaded with essential purpose and context. Every word adds value.

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

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

With no output schema, the description omits what information is returned for each session (e.g., ID, timestamps). Incomplete for an agent to understand the tool's output.

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?

No parameters exist, schema coverage is 100%, and the description correctly provides no parameter details. Baseline 4 for 0 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 clearly states the tool lists active HoneyBook portal sessions, specifies the source (captured via use_magic_link), and distinguishes from siblings like get_workspace 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 implies usage context (sessions from use_magic_link) but does not explicitly state when to use this tool versus alternatives or exclude scenarios.

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

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

The description adds value beyond the readOnlyHint annotation by stating that an empty array is returned if no payment methods are saved. This provides expected behavior. No other behavioral traits (e.g., rate limits, auth) are mentioned, but the annotation already covers read-only nature.

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, well-structured sentence that immediately communicates the tool's purpose. There is no extraneous information, and every word adds value.

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

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

For a simple read-only list tool with a single optional parameter and no output schema, the description is fully adequate. It explains the return case (empty array) and the parameter is well documented in the schema. No gaps remain.

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

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

The input schema has 100% description coverage for the single parameter 'origin', including its meaning and optionality. The tool description does not add any additional clarification about parameters beyond what the schema provides, so 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 clearly states the action 'List', the resource 'payment methods', and the scope 'for your client account with a vendor'. It distinguishes itself from sibling tools which deal with workspaces, invoices, contracts, etc., and none overlap with payment methods.

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 the tool is for retrieving saved payment methods but does not provide explicit guidance on when to use it over alternatives, nor does it mention prerequisites or exclusions. However, the context makes it fairly 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, so the description is consistent. It adds context about file types but does not disclose potential behavioral traits like pagination, limits, or session requirements beyond the origin parameter.

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 sentence that is efficient and front-loaded with the key action and resource. It is concise without missing essential information.

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

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

The description covers the basic purpose and filtering option, but without an output schema, it does not explain the return format or structure. For a simple list tool, it is adequate but not fully 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%, with clear parameter descriptions. The tool description adds examples of file types but no additional meaning beyond the schema. 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 states the action (list) and resource (files shared by vendor) with examples (contracts, invoices, etc.), and it is well-distinguished from sibling tools like get_workspace_file and list_active_sessions.

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

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

No explicit guidance on when to use this tool versus alternatives. The description implies its use for listing shared files with optional filtering, but lacks direct comparisons or when-not-to-use 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?

Annotations already indicate destructive hint (mutation). The description adds that the tool returns a deep link and requires confirmation, informing the agent of the behavioral outcome 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?

Two sentences, no wasted words. Front-loaded with purpose and immediately provides key behavioral details. Perfectly concise.

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 3 params and no output schema, the description covers purpose, behavioral caveat, and a parameter requirement. It could mention what the deep link entails but 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 has 100% coverage, so baseline is 3. The description adds crucial constraint on the confirm parameter ('Requires confirm:true'), adding value beyond the schema's description.

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 pays an invoice from a vendor, which is a specific verb+resource. It distinguishes from siblings like get_workspace or sign_contract by focusing on payment.

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 mentions the requirement 'confirm:true' and notes that v1 returns a deep link instead of headless payment, providing context for usage. However, it lacks explicit when-not or alternative tool 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?

The description discloses that v1 returns a deep link instead of signing headlessly, which adds behavioral context beyond the annotations. The 'destructiveHint: true' annotation is consistent with signing a contract, and the description provides specific version 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?

Two sentences with no wasted words. The primary action is stated first, followed by a critical behavioral note and a requirement. Perfectly front-loaded.

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

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

Given no output schema, the description mentions the tool returns a deep link, which is sufficient for basic understanding. It covers the essential behavioral trait (headless vs. deep link) and the confirm requirement. Missing details on error handling or return format but acceptable for a simple 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 coverage is 100%, providing baseline 3. The description adds value by emphasizing the 'confirm' parameter requirement and the optional nature of 'origin', which goes beyond the schema descriptions.

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

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

The description clearly states the tool signs a contract received from a vendor, which is a specific verb+resource. It distinguishes from sibling tools like 'pay_invoice' and 'list_workspace_files' by focusing on signing contracts.

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

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

The description explicitly requires 'confirm:true' and notes that the 'origin' parameter is optional when only one session is active. It provides clear context for usage, though it does not explicitly state when not to use or list 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?

The description goes well beyond the readOnlyHint annotation by disclosing that it reads localStorage, writes to ~/.honeybook-mcp/sessions.json, does not sniff live requests, does not navigate to the magic link, and works regardless of page idle state. This is fully consistent with readOnlyHint=false, so no contradiction.

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

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

The description is front-loaded with the primary purpose, followed by prerequisites, mechanism, output location, inter-tool dependency, and a parameter caveat. Every sentence earns its place; no wasted words.

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

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

Given the tool's complexity as a setup/authentication capture, the description covers prerequisites, the exact mechanism, the file output, how other tools depend on it, and parameter semantics. There is no output schema, but the description sufficiently explains what the tool does and what it produces.

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 provides a detailed description of magic_link_url with 100% coverage. The tool description adds behavioral nuance by explicitly stating the argument is used only to derive the portal origin/cache key and that the tool does NOT open or navigate to the URL, which is valuable 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 opens with a specific verb and resource: 'Capture a HoneyBook client-portal session via the fetchproxy 0.3.0 browser extension.' It clearly distinguishes this tool from sibling tools, which consume sessions, by explaining that it is the setup mechanism that writes session data for other tools to use.

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 extension, open signed-in tab, leave it open) and explains how all other tools use the most-recently-activated session by default. It does not explicitly name alternative tools or state when not to use this tool, but the context is strong enough to guide the agent.

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