Doorman

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

With no annotations, the description carries the burden and delivers: it discloses what gets attached (plan, forms, recent errors, never keys) and where the reply goes (account email). This is useful behavioral context for a send operation, though it doesn't state rate limits or whether the action is idempotent.

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?

Tight, front-loaded prose that answers what, why, what's included, and where the reply goes in three sentences. No waste.

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 key details for a support-contact tool: what it does, what data is attached, and that the reply is emailed. Missing only minor details like whether the message is required (though schema covers that) or expected response. Good completeness given 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 coverage is 75%, so the schema already documents most parameters including the api_key header note. The description mentions attaching the error ('with the error you hit') which maps to the error parameter, but adds little 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?

States a specific action (send a support problem) and target (Doorman's founder), with a clear outcome ('reply goes to the account email'). It doesn't explicitly distinguish from siblings, but no sibling covers support-contact, so the purpose reads clearly.

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?

Provides clear context: use when stuck or something isn't working, and explicitly says 'Use it instead of guessing at a fix.' This gives the when-to-use condition without naming alternative tools, which is sufficient for a one-off support 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?

With no annotations, the description carries the full behavioral burden. It says nothing about authentication requirements, whether duplicate form names fail, whether creation is reversible, rate limits, or what a successful call returns. The api_key parameter implies auth but the description itself gives no behavioral context for a write operation.

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 no filler or redundancy. The word "another" is slightly odd without prior conversational context, but nothing in the 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?

This is an 8-parameter mutation tool with no annotations and no output schema, so the description should ideally cover auth expectations and create-vs-update behavior. The schema handles parameter documentation well, but the behavioral envelope an agent needs before calling a write tool is only partially inferred.

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 8 parameters including the kind enum and each delivery target. The description adds no format, default, or interaction detail beyond the schema, so the baseline 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 states a specific verb and resource ("Create another form endpoint") and clarifies the unit of creation with the parenthetical about one endpoint per distinct form. It is clearly distinguishable from read-side siblings like doorman_list_forms or doorman_list_submissions, though it never contrasts with doorman_update_form.

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 parenthetical "one per distinct form on the site" implies when to create (a new distinct form) versus reuse an existing endpoint, but there is no explicit when-not guidance, no mention of doorman_update_form as the alternative for existing forms, and no prerequisites 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, and the description's 'Read' is consistent with that. It adds that the content mirrors /llms.txt, which tells the agent exactly what it will get back, a useful behavioral detail 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 tight sentences, no waste. The purpose is front-loaded and the call-first instruction follows immediately.

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?

A parameterless read-only docs tool with no output schema needs little more; the description covers purpose, content equivalence, and invocation timing. Nothing essential is missing, though a note on expected output format would make it fully self-contained.

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?

Zero parameters, so per the rubric the baseline is 4. There are no parameter semantics to clarify and the description correctly doesn't invent any.

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?

Specific verb+resource: 'Read how Doorman works and how to integrate it', with the clarifying detail that it returns the same text as /llms.txt. Clearly distinguishable from every sibling, which are all action-oriented (create_form, list_submissions, etc.).

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 'Call this first if you haven't used Doorman before', giving a clear condition for invocation. It doesn't name alternatives or state when NOT to call it, but for a bootstrap-docs tool the ordering guidance is the main thing an agent needs.

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 tells the agent this is a safe read, so the bar is lower. The description adds that the result is paste-ready code and that the 'fetch' variant includes timeout and fallback behavior, but says nothing about auth requirements beyond what the schema states, nor about the shape/size of the returned snippets.

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 front-loaded sentence stating the action, followed by a compact routing list. The second clause is dense to the point of being run-on, 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?

For a no-output-schema read tool, the description should fully cover the platform enum it depends on, yet five documented enum values (ajax, curl, webflow, framer, wordpress) get no guidance, so an agent selecting those values is guessing. Otherwise adequate for a simple code-retrieval 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 67% and the platform enum has no per-value description in the schema, so the description's mapping of platform values to deployment contexts adds real meaning. It falls short by covering only 8 of the 13 enum values, leaving the no-code and ajax/curl options undefined.

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 ('Get ready-to-paste integration code for a form'), with scope narrowed to 'a given platform'. No sibling tool in the list produces integration code, so the agent can distinguish it 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?

Gives value-level routing guidance ('html' for static sites, 'react' for SPA client components, 'fetch' for Workers/Node/Next/Deno, backend frameworks when the form posts to your own backend). It never names an alternative tool or a when-not condition, and it silently omits five valid enum values (ajax, curl, webflow, framer, wordpress).

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 no annotations, the description carries the full burden and does disclose the key side effect that labeling 'real' delivers a held or dropped submission. However, it omits reversibility of the action, whether the readOnly-style safety profile applies, and auth requirements (the api_key behavior lives only 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?

A single sentence with the consequence front-loaded in the parenthetical; no filler and nothing redundant.

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 two-required-param mutation tool with no annotations or output schema, the crucial behavioral fact (delivery on 'real') is stated. Remaining gaps are minor: no error/failure behavior and no explicit note on irreversibility.

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 leaves the enum values 'real' and 'spam' undefined, so the description's explanation that 'real' triggers delivery adds real meaning beyond the schema. submission_id and api_key are covered by the schema itself, so 67% coverage is largely compensated.

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 (mark) and resource (submission) plus the two terminal states (real/spam), and the parenthetical clarifies the consequence of labeling something real. It doesn't name a sibling to distinguish itself from, e.g., doorman_test_submission, but the purpose is unambiguous.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as doorman_test_submission or doorman_list_submissions. The held/dropped parenthetical hints at context but never states the condition under which an agent should call this tool.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds a modest signal by saying the result includes action URLs and settings, which hints at the payload shape, but it does not discuss pagination, whether all forms are returned, or any auth behavior beyond what the api_key schema already documents.

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 no filler; the resource and the notable return fields come first. Slightly terse, but nothing 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?

For a trivial read-only list with one optional parameter and no output schema, this is minimally adequate. The mention of action URLs and settings partly compensates for the missing output schema, but pagination, result limits, and any empty-account behavior are unaddressed.

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?

Only one optional parameter (api_key) exists and its schema description is 100% covered, including the dm_live_ prefix and the no-Authorization-header condition. The description adds nothing about it, so the baseline 3 for fully documented schema 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?

Names a specific verb (List) and resource (the account's forms), plus light scope detail (action URLs and settings). It is clear what the tool does, but it never distinguishes itself from near-neighbors like doorman_list_submissions or doorman_list_forms-style reads, so an agent must infer the split from names alone.

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 when-to-use guidance, no prerequisite (e.g. authentication already handled), and no mention of alternatives such as create_form/update_form for the write path. Usage must be inferred entirely from the verb and from sibling names.

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 safety is covered structurally. The description contributes that results include verdicts and that some submissions are 'held... waiting for a human', which tells the agent what state means. It omits pagination/limit behavior and ordering semantics for a 'recent' 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?

Two short sentences, result content front-loaded, usage rule second — no filler. It is tight, though the extreme brevity leaves room that could have been spent on the undocumented filters.

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

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

For a 5-parameter, no-output-schema list tool, the description leaves most of the request surface unexplained: no hint about route values, limit/default page size, form_id scoping, or result shape. An agent can call it, but only with guesswork about the filters.

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 only 40% across 5 parameters. The description only explains review=true; limit, route (an enum with deliver/hold/drop), and form_id are left undiscussed, so it fails to compensate for the coverage gap. Low-coverage schemas require the description to carry more of this load.

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 submissions) plus content of the result (their verdicts), and implicitly distinguishes a filtering mode via review=true. It doesn't name any sibling, but list_forms / label_submission are clearly different operations, so the agent can tell what this does 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?

Gives one concrete usage rule — 'Use review=true for held ones waiting for a human' — which maps a filter to an intent. However it says nothing about when to prefer this over label_submission or test_submission, nor when not to use it, so guidance is partial and implied.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It conveys that a sample delivery is sent to external destinations and that per-destination success is reported, but it omits side-effect details such as whether real emails/Slack messages are sent, quota implications, required permissions, or whether the action is reversible.

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 delivers the core action and outcome efficiently.

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 with two fully documented parameters and no output schema, so the description needn't explain return values. However, with no annotations and a side-effecting test-send operation, the description should disclose more about permissions, side effects, or safety to be 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%, so both api_key and form_id are fully documented in the input schema. The description adds no additional parameter meaning, which meets the baseline of 3 when the schema does the heavy lifting.

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'), resource ('sample delivery'), and scope ('form's email/Slack/webhook destinations') plus the outcome ('report whether each one worked'). It clearly identifies what the tool does, though it does not explicitly name or differentiate itself from the sibling doorman_test_submission.

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 guidance on when to use this tool versus alternatives like doorman_test_submission or when not to use it. The implied context is testing delivery destinations, but prerequisites, exclusions, and alternative selection criteria are absent.

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 no annotations, the description carries the full burden and does it well: it discloses the return payload (form id, action URL, api_key), requires credential handling ('store it as DOORMAN_KEY... never commit it'), and explains the pre-confirmation state ('nothing is emailed to them; 100 checks; Slack and webhooks work'). These are exactly the behavioral facts an agent cannot infer from 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?

Front-loaded with the core action and credential guidance, and most sentences earn their place. The parenthetical about '100 checks; Slack and webhooks work' is slightly tangential and the passage runs long, but nothing is wasted or circular.

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

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

For a multi-effect provisioning tool with no annotations and no output schema, the description compensates by explaining both the side effects (form creation, confirmation email) and the return values. An agent has everything needed to invoke and handle the result 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 schema already documents all five parameters, including the mode enum's watch/enforce tradeoff. The description adds only a hint about email ('Ask the user for their email first') and does not clarify site_context or site_url beyond what the schema states. 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?

States a specific verb and resource ('Create a Doorman account... with a first form and an API key') and its scope. It is clearly distinguishable from siblings like doorman_create_form, which acts on an existing account rather than provisioning one.

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

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

Explicit when-to-use and when-not: 'Only for new users: if they already have an account, ask for a key instead,' plus the sequencing instruction 'Ask the user for their email first.' It stops short of naming the sibling (e.g. doorman_whoami) an agent should call to determine whether an account already exists.

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 no annotations, the description carries the full burden and does well: 'Free, not forwarded, not counted' discloses the absence of billing, delivery, and quota side effects. It does not mention auth requirements or what the returned judgment looks like, but the schema covers the api_key prerequisite.

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 purpose, then the safety/cost guarantees, then usage. Every sentence 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 4-parameter tool with no output schema and no annotations, the definition covers intent, cost, and side effects but never hints at the shape of the result beyond the verb 'judge' (e.g. a label/verdict). An agent knows how to call it but not quite what it gets back.

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 all four parameters including form_id format (f_...) and api_key format (dm_live_...) are already documented. The description adds no parameter-level detail, which is the expected baseline when the schema does 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+resource: judging a sample message against a form's settings. It is clearly distinguishable from list/create/update siblings, though it never explicitly names its closest sibling, doorman_send_test_delivery, so the boundary between 'test submission' and 'test delivery' is left to inference.

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 context ('after setup') and even suggests a test strategy (one genuine enquiry and one sales pitch). It stops short of stating when NOT to use it or contrasting it with doorman_send_test_delivery, which is the most likely alternative an agent would consider.

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 no annotations, the description carries the full behavioral burden and does not meet it. It never states whether this is a partial update (are omitted fields preserved or reset?), what permissions/API key are required, or whether threshold changes affect in-flight submissions — all critical for a 15-parameter 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?

A single front-loaded sentence with zero filler: verb, resource, then a compact enumeration of the setting categories. 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?

For a 15-parameter mutation tool with no annotations and no output schema, the description is too thin. It omits partial-update semantics, auth handling, and any indication of what a successful update returns or affects — gaps the structured fields do not fill.

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 93%, so the schema already documents nearly every parameter (mode, deliver_at, drop_below, allow_list, etc.). The description's grouped categories loosely map to those parameters but add no syntax, defaults, or edge-case meaning beyond the schema, so the baseline 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?

States a specific verb ('Change') and resource (a form's settings) and enumerates the setting categories (context, destinations, thresholds, watch mode, allow/block lists), which lets an agent distinguish it from doorman_create_form or doorman_list_forms. It stops short of explicitly naming the sibling it is not, so a 5 is not warranted.

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 when-to-use guidance, no prerequisites, and no named alternative (e.g. create vs update, or when to prefer watch mode over enforce). The word 'Change' weakly implies an existing form, but nothing routes the agent between this and doorman_create_form.

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 establishes this as a safe read, so the description's main added value is naming the returned payload (account, plan, usage). It says nothing about auth requirements, rate limits, or what 'usage' covers, but for a trivial read tool with annotation coverage this is adequate. 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?

It is a single fragment with zero filler, but it is under-specified rather than well-structured prose — there is no framing sentence to front-load, and the terseness reads as abbreviation rather than economy.

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-required-parameter, read-only identity tool with a fully documented schema and no output schema, the description covers the essential question of what the agent gets back. Only the absence of any usage framing keeps it from being 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%: the api_key parameter is fully documented in the schema, including the conditional 'only needed if the MCP connection has no Authorization header' caveat. The description adds nothing about parameters, so the baseline 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 is a noun phrase ('Account, plan and this month's usage') rather than a verb+resource statement, but combined with the name whoami it does convey that it reports the caller's own account context. It gives no differentiation from siblings like doorman_contact_support or doorman_docs, and an agent must infer that this is a self-identity/account read. Vague but interpretable.

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 when-to-use guidance at all — no statement of the condition that should select this over any sibling, and no exclusions. The agent can only infer usage from the tool name.

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