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 so: it discloses the email-confirmation gate ('until the user clicks the confirmation link... nothing is emailed'), the exceptions (100 checks, Slack and webhooks work), the secret-handling requirement (store as DOORMAN_KEY, never commit), and the fact that it also creates a first form. These are real side effects and constraints an agent needs.

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

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

Front-loads the core action and sequences the workflow (ask for email → account creation → confirmation email → key handling). It is somewhat dense and run-on with several parentheticals, but nearly every clause carries operational 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 multi-step, no-output-schema onboarding tool, the description covers the return values (form id, action URL, api_key), the post-call handling, the existing-user fallback, and the delivery caveat before email confirmation. Nothing material 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 all five parameters are already documented in the schema, including the mode enum's watch/enforce semantics. The description adds no syntax or format detail beyond echoing email and the returned api_key, 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?

Opens with a precise verb+resource: 'Create a Doorman account for the user with a first form and an API key.' It also distinguishes itself from siblings like doorman_create_form and doorman_whoami by making clear this is the new-user onboarding path that bundles account + first form + key.

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

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

Explicitly states prerequisites and exclusions: 'Ask the user for their email first' and 'Only for new users: if they already have an account, ask for a key instead.' This gives a clear when-to-use and a when-not-to-use with the alternative action named.

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. It implies mutation but does not disclose partial-update semantics, whether changes are reversible, permission requirements, or how mode switching (enforce vs watch) affects live traffic.

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. It is tight, though given 15 parameters it borders on under-specification rather than true conciseness.

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 15-parameter mutation tool with no annotations and no output schema needs more: partial-update behavior, auth via api_key vs header, and the effect of threshold changes are all unaddressed. The description covers the 'what' but not enough for correct invocation.

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

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

Schema description coverage is 93%, so the schema already documents nearly every parameter, including the mode enum's watch semantics and threshold defaults. The description merely names setting categories and adds no syntax or format 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?

States a specific verb ('Change') and resource ('a form's settings') and enumerates the setting categories touched (context, destinations, thresholds, watch mode, allow/block lists). This is clearly distinguishable from the create_form sibling, though it never names it explicitly.

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 versus doorman_create_form, nor any prerequisite (e.g., the form must already exist). Critically, for an update tool it never says whether omitted fields are left unchanged or reset, which is the single most important usage question.

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.