Click2Mail MCP by usefulapi

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

Annotations already flag destructiveHint/readOnlyHint/idempotentHint, and the description adds the operationally critical context they don't carry: the exact failure conditions, that the mailing is stopped permanently, that user confirmation is required, and the underlying endpoint. That is meaningful disclosure beyond the structured hints.

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

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

Three compact sentences with the write classification, the restriction, the safety gate, and the alternative all front-loaded; the endpoint hint at the end. 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 2-param destructive mutation with no output schema, it covers the safety profile, failure modes, prerequisite approval, and the sibling to use instead. Nothing an agent needs in order to call it correctly 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 already constrains confirm to true, so the schema does the heavy lifting. The description still contributes intent by framing confirm as a user-approval gate ('get the user's explicit go-ahead first'), which is more actionable than the schema's terse 'user approved' wording.

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 an explicit verb and resource plus a state qualifier: 'WRITE: cancel a SUBMITTED job.' It also names the sibling for the adjacent-but-different operation (drafts → click2mail_delete_job), so an agent can discriminate it from delete_job and from submit_job without opening a 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 both when-to-use and when-not: it states the vendor restriction (invoice-paid jobs only, only before mailing processing starts, otherwise it fails) and redirects draft removal to click2mail_delete_job. It also names a prerequisite (explicit user approval) before invocation.

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, destructiveHint=false and openWorldHint=true; the description's 'Read-only: nothing is saved or sent' reinforces and slightly clarifies that no data is persisted. It adds little beyond that — no mention of rate limits, per-call cost, or what happens to invalid addresses.

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

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

Three tight sentences, front-loaded with the core purpose and the read-only guarantee before the endpoint detail. The 'POST /molpro/addressCorrection' line is marginal internal detail but not harmful.

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?

No output schema exists, so the description should explain what comes back — corrected/standardized address fields, per-address success or failure indicators. It doesn't, leaving the agent guessing about the response shape of a validation tool whose whole value is the corrected result.

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

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

Schema description coverage is 0%, so the description must compensate: it does say the input is up to 100 US postal addresses and implies which fields matter (validation requires address1/city/zip, state optional), but it never documents the item structure or the significance of name/address2. Partial compensation only.

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

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

Specific verb+resource: 'validate and standardize US postal addresses' with the USPS/CASS standard named and a clear scope cap of 100. It implicitly separates itself from click2mail_create_address_list by stressing 'nothing is saved,' but never names a sibling explicitly, which keeps it short of a 5.

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

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

'before mailing' implies the workflow position (pre-flight cleanup before creating a job or address list) but gives no explicit when-to-use/when-not or pointer to create_address_list for persistence. Usage is inferable rather than stated.

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

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

Annotations already declare this is a non-destructive, non-idempotent, open-world write; the description adds substantive context beyond that: the list is asynchronously CASS-standardized, so the caller must poll for a status rather than assume readiness, and the call creates data only with no mailing or charge side effects. This is exactly the kind of post-call behavioral knowledge annotations cannot convey.

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

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

Four compact sentences with zero filler: the write nature and scope come first, then the polling workflow, then the side-effect disclaimer, then the endpoint. Each sentence contributes distinct 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?

With no output schema, the description compensates by telling the agent that the created list has an id, that the id is needed downstream, and that readiness is signaled by status 3 on a separate tool. That is sufficient for an agent to both call this and act on its result.

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

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

Schema coverage is 50% and the description says nothing about the required 'name' parameter, nor does it explain address-field requirements beyond restating the 500 cap already encoded as maxItems. The nested per-field descriptions in the schema carry most of the semantics, so the description only marginally adds value.

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 an explicit verb+resource pair ('WRITE: upload a recipient address list') and adds scope ('up to 500 addresses') and the backing endpoint (POST /molpro/addressLists). An agent can immediately distinguish this from click2mail_get_address_list or click2mail_create_job.

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 lays out the full workflow: create the list here, poll click2mail_get_address_list until status 3, then pass the id to click2mail_create_job. It also states the negative condition that nothing is mailed or charged, which separates it from job-creation tools.

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

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

Adds real value beyond annotations: the draft lifecycle, the deferred charging, the handoff to submit_job, and the return value (job id). It does not address non-idempotency (duplicate calls create duplicate drafts) or authentication, which the annotations only flag indirectly via idempotentHint=false.

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 'WRITE:' marker, then scope, safety behavior, prerequisite, and return value in four short sentences with zero filler. The trailing POST endpoint is minor but harmless orientation.

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, 9-required creation tool with no output schema, the description covers intent, side-effect posture, prerequisite lookup, and return value. Gaps are minor: no mention of validation failure behavior or what happens to draft jobs left unsent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds actionable meaning the schema cannot: the option-valued parameters must match strings from click2mail_get_product_options, which matters because the schema has zero enums. It doesn't clarify which parameters are immutable after creation.

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 mailing job from an uploaded document and an address list') and pairs it with the crucial qualifier that the result is a draft, which cleanly separates it from click2mail_submit_job. An agent can route to it without opening a sibling schema.

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

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

Explicitly says the job stays in Editing status and nothing is printed, mailed, or charged until click2mail_submit_job, and directs the agent to pull exact option strings from click2mail_get_product_options. Both the when-to-use and the when-not are 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is known. The description adds genuinely useful preconditions (eligible statuses), the failure case for submitted jobs, and the raw endpoint. It stops short of saying whether deletion is recoverable or what an error looks like, so it is strong but not exhaustive.

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 'WRITE:' then the action, the constraint, the alternative, and the endpoint in three compact clauses. Every clause carries distinct information; nothing is redundant with the title or annotations.

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

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

For a one-parameter destructive tool with full annotation coverage and no output schema, this covers almost everything needed: scope, exclusions, alternative, and endpoint. Only the failure behavior and irreversibility are unstated, which is a minor gap given the destructiveHint.

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% for the single required job_id, and the schema description already says 'an unsubmitted draft'. The description reinforces that the id must reference an unsubmitted job, which is helpful validation context but adds little beyond the schema. Baseline 3 applies when the schema fully documents the parameter.

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

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

States a specific verb (delete) and resource (job) with an explicit scope restriction: only jobs in Editing or PendingProofAcceptence status. It explicitly distinguishes itself from click2mail_cancel_job, so an agent can route correctly without opening either 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 both the when ('a job that has not been submitted') and the when-not ('Submitted jobs cannot be deleted'), plus the named alternative ('use click2mail_cancel_job'). Nothing about tool selection is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description's 'nothing is charged' usefully reinforces that a cost estimate has no financial side effect, and naming the GET endpoint adds a little context, but return shape and the effect of optional fields on the estimate are undisclosed.

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, front-loaded with the purpose and the no-charge guarantee, then the option-string constraint. No filler, and the endpoint is demoted to the tail.

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

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

For a 13-parameter, 8-required tool this covers the two things that most easily go wrong: sourcing valid option strings and the fact that nothing is created. With no output schema, the description could say what the estimate returns (total, breakdown by component), and it is silent on the four optional parameters.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: the example values in the schema are illustrative only, and the description pins them to get_product_options as the authoritative source. It also signals quantity is a cost driver, though it says nothing about the optional parameters (payment_type, number_of_pages, non_standard_quantity, international_quantity) that meaningfully change the estimate.

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 ('Estimate the cost of a mailing from its print options and quantity') and adds the key scope qualifier that nothing is created or charged. It doesn't explicitly differentiate from click2mail_get_job_cost, the nearest sibling, but the input-based framing makes the distinction inferable.

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

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

Gives a concrete precondition: 'Use the exact option strings from click2mail_get_product_options', which is exactly the kind of routing an agent needs for an enumeration-heavy tool. It stops short of naming exclusions (e.g. use get_job_cost when a job 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?

Annotations already cover the safety profile (readOnlyHint true, destructiveHint false, openWorldHint true), so the description's added value is the semantics of the result: that a processing state of 3 means CASS-standardized and job-ready. That is genuinely useful behavioral context not present in the schema or annotations. It stops short of saying whether the call blocks, costs credits, or fails on a nonexistent id.

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 compact sentence that front-loads the return contents, followed by the endpoint. Every clause carries information; the trailing GET path is mildly redundant for an agent but useful for traceability, and 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?

With no output schema, the description steps in to explain what the response contains (state, name, counts) and decodes the critical enum value 3, which is the main thing an agent needs. Missing only the contrast with the sibling info tool and any error/polling behavior.

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

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

Schema description coverage is 100% and the single parameter is documented as an id obtained from click2mail_create_address_list, so the schema carries the burden. The description adds nothing about the id beyond what is already in the property description, making baseline 3 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?

Specific verb (get) plus resource (address list) plus what is returned: processing state, name, counts, and the underlying endpoint. It clearly reads as a status read, but it never distinguishes itself from the close sibling click2mail_get_address_list_info, so an agent must still guess which of the two to call.

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 and no mention of the obvious alternative, click2mail_get_address_list_info, nor of any prerequisites such as polling after click2mail_create_address_list before starting a job. The intended usage (check readiness) is only implied by the 'ready for a job' phrasing.

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, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds the paging default behavior and the underlying GET endpoint, but says nothing about whether standardization results are cached/stale, whether the call triggers validation, or any rate limits. Useful context, but limited.

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, front-loaded with what the tool returns before the paging mechanics. The trailing endpoint path is marginal but potentially useful for debugging. Nothing is redundant or bloated.

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 does the important work of telling the agent the response contains addresses with per-address standardization results, and it explains pagination. It does not describe the response envelope (e.g., total count, list metadata) before the agent commits, which is the main remaining gap for a read-only detail tool.

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

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

Schema description coverage is 100%, so limit, offset, and address_list_id are already fully documented, including the 10-item vendor default and zero-based offset. The description only restates the paging intent, adding no new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description names a specific verb and resource (details of an address list) and specifies what is actually returned: the list's addresses plus each address's standardization result. That is far more informative than the title alone. It stops short of distinguishing this tool from the sibling click2mail_get_address_list, which an agent would need to tell apart.

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

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

Usage is implied by stating that results are paged by default (10 addresses) and by naming the limit/offset paging model, so the agent knows to paginate. However, there is no explicit when-to-use guidance and no statement about when to prefer click2mail_get_address_list or click2mail_check_addresses instead.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds value by disclosing the two return fields and the endpoint, and by explaining what `allowNegative` means operationally — more than the annotations alone provide.

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

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

Two tight sentences: the returned fields first, then the action-oriented usage hint, then the endpoint. Every clause carries information; nothing is padding.

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?

There is no output schema, but the description explicitly enumerates both return fields and their meaning, which is exactly what an agent needs for this trivial zero-param read. Nothing material is missing.

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

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

The tool takes zero parameters, so the baseline is 4; the description correctly implies no inputs are needed by describing only the returned values.

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

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

The description names a specific resource (prepaid credit balance) and the exact fields returned (`balance`, `allowNegative`), plus the underlying endpoint GET /molpro/credit. No sibling tool touches account credit, so an agent can select it unambiguously.

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

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

It gives an explicit trigger: "Check it before submitting a job paid with User Credit." That is clear usage context, though it doesn't rule out other cases (e.g. estimate_cost reads) or name alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real context beyond them: the result depends on payment type and returns an itemized cost profile, and implies the job must already exist. It doesn't cover failure modes (invalid or unsubmitted job id) or whether the quote expires.

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 plus an endpoint path; the purpose and the workflow instruction are both front-loaded and nothing is 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?

With no output schema, the description does tell the agent what comes back at a high level (postage, printing, fees) and why it matters. The main gap is the effects of coupon_code and details, which an agent may need to choose non-default values.

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 baseline is 3. The description reinforces payment_type dependence and hints at the itemized breakdown, but says nothing about 'details' or 'coupon_code', the latter of which has no schema description at all and is therefore documented nowhere.

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 and resource ('exact cost of a created job') and enumerates the cost components (postage, printing, fees), which separates it from a generic cost lookup. It does not explicitly contrast with click2mail_estimate_cost, the most confusable sibling, but 'created job' versus an estimate carries implicit differentiation.

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

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

Gives an explicit workflow cue: 'Read it before click2mail_submit_job', which is actionable sequencing advice. It doesn't say when to use this rather than click2mail_estimate_cost, nor any exclusions (e.g., job not yet created), so it stops short of full routing guidance.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description adds the underlying endpoint (GET /molpro/jobs/info/{id}) and the shape of what comes back, but says nothing about auth requirements, error behavior for unknown job ids, or scoping to the caller's account.

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

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

Two compact sentences, front-loaded with the substantive return-content list followed by the endpoint. No filler or redundancy.

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

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

With no output schema present, listing the returned field groups is exactly the right compensation and covers most of what an agent needs. Minor gap: no indication of how a nonexistent or unauthorized job id is reported.

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?

There is a single parameter and the schema documents it fully ('Click2Mail job id.', integer, >0), so coverage is 100% and the schema carries the meaning. The description never mentions job_id, so it adds nothing beyond the schema — the baseline 3 for high schema coverage.

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

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

Names a specific verb-resource pair (get full job details) and enumerates what 'details' covers — print options, document, address list, dates, cost, payment — which lets an agent distinguish it from the narrower siblings get_job_status, get_job_cost and get_job_tracking. It stops short of explicitly stating that routing relationship, so not a 5.

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

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

The field list implies this is the comprehensive per-job read, versus the single-aspect siblings, but there is no explicit 'use this when...' or 'use X instead for...' clause. The agent has to infer the choice from content coverage alone.

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, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds real value beyond that by disclosing the return shape (numeric status plus description plus status URL) and the underlying endpoint GET /molpro/jobs/{id}, which the agent otherwise could not infer.

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 covers the return contents and an example, followed by the endpoint in a compact clause. Every element earns its place and there is no filler.

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

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

For a simple single-parameter read with no output schema, the description supplies enough about return values (status number, description, URL) to call it correctly. The one remaining gap is that it never clarifies how this differs from get_job_info or get_job_tracking, which an agent choosing among 20+ siblings would want.

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?

There is a single required parameter, job_id, with 100% schema description coverage, so the schema already documents it. The description does not add syntax, format, or sourcing guidance for job_id, so the baseline of 3 applies.

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

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

The description states a specific resource (job status) and enumerates what is returned: numeric status, its description, and the status URL. It is clearly a read of job status. It does not explicitly distinguish itself from siblings like get_job_info or get_job_tracking, so it lands at 4 rather than 5.

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

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

Usage is only implied: an agent can infer this is called to poll a job's state, and the example ('9 = Editing') hints at lifecycle checking. There is no explicit when-to-use guidance, no mention of when to prefer get_job_info/get_job_tracking, 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 readOnly and openWorld, so the description's added value is the refresh cadence (daily) and the staging limitation — real behavioral facts not in structured data. It does not say what an empty result means (untracked/not yet scanned) or whether results are paginated.

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 tightly packed sentences plus the endpoint: return shape first, then operational caveats. No filler, front-loaded with what the caller gets.

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 usefully enumerates the returned fields and the daily-update/staging constraints, which is enough to call it correctly. Minor gaps remain around empty-result semantics and response size for large jobs with tracking_detail enabled.

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

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

Schema coverage is 100%, so baseline is 3. The description's mention of 'per mail piece barcode' hints at the bar_code filter but does not explain tracking_type (IMB vs IMPB) or that tracking_detail expands per-piece scan history — both are left entirely to the schema.

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

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

States a specific verb+resource ('USPS tracking for a submitted job') and enumerates the per-piece data returned (barcode, address, status, date, location), plus the underlying endpoint. It is distinguishable from click2mail_get_job_status/get_job_info by being piece-level carrier tracking, though it never names those siblings 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?

'Tracking updates once a day, so one call per day is enough' tells the agent both the polling cadence and that redundant calls are wasted, and 'nothing is tracked on staging' gives a clear when-not condition. It stops short of naming which sibling to use instead when the agent wants submission status rather than carrier scans.

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, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds real behavioral value beyond that: the reply is authoritative (must use exact strings verbatim) and it names the concrete endpoint GET /molpro/productOptions. It doesn't describe pagination or response shape, keeping it below 5.

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

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

Two compact sentences plus the endpoint path. The resource scope is front-loaded and the downstream-usage instruction follows immediately; 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?

With no output schema, the description correctly compensates by enumerating the returned dimensions (document class, layout, production time, envelope, color, paper, print option, mail class). It lacks response structure/format detail, but an agent knows what it gets and how to use it, which is sufficient for a simple read-only lookup.

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

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

Schema description coverage is 100%, so both parameters (document_class with example values, skip_bulk_print) are already well documented. The description lists 'document class' as one of the option dimensions but adds no filtering syntax or format guidance beyond the schema. Baseline 3 applies 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 names the resource (mail products and valid option combinations for the account) and enumerates the option dimensions returned, so the agent knows this is a catalog/lookup tool. It is distinguishable from siblings like click2mail_list_documents or click2mail_get_credit, though the verb itself is implicit ("The mail products...") rather than stated as 'list/retrieve'.

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 downstream usage: use the exact strings from this reply in click2mail_create_job and click2mail_estimate_cost. That is a strong, actionable routing cue. It stops short of 5 because it doesn't say when NOT to call it or how it relates to sibling listing tools (e.g., list_documents).

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real context beyond that: the sort order ('most recent first'), the returned fields, and the underlying GET endpoint. Pagination mechanics are left to the schema rather than described, which keeps it at a 4.

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

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

Three short sentences, each carrying distinct information: what is listed, the returned fields and order, the downstream use, and the endpoint. Nothing is redundant and the core purpose is 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?

With no output schema, the description usefully compensates by naming the returned fields and ordering. For a read-only, zero-required-parameter list tool this is nearly complete; only pagination behavior and any result-size caveats are omitted.

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 offset, document_class and number_of_documents parameters are already fully documented. The description adds nothing about filtering or page size semantics, which is the correct baseline 3 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 and resource ('List the documents uploaded to the account') and even enumerates the returned fields (id, name, class, pages). This clearly distinguishes it from the other list_* siblings such as click2mail_list_jobs_by_app_signature and click2mail_list_return_addresses.

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?

'Use a document id when creating a job' gives a concrete downstream use that routes the agent toward click2mail_create_job. There are no explicit when-not conditions or named alternative list tools, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the useful cross-tool note that click2mail_create_job sets the appSignature, but says nothing about result ordering, pagination limits, or empty-result 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?

One tight sentence that front-loads the resource and filter, followed by a short endpoint reference. The raw 'GET /molpro/jobs/appSignature' adds little an agent needs, but the total length is minimal and there is no padding prose.

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 four-parameter read with full schema coverage and no output schema, the description covers the core purpose, yet it never indicates the shape or ordering of the returned job list, and pagination behavior is left entirely to the schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes beyond the schema's bare 'The appSignature value' by defining the parameter as the label an integration applies to its jobs and naming the tool that sets it, which helps the agent supply a correct value.

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 (List) plus resource (jobs) and the exact filter (appSignature), and explains what an appSignature is by tying it to click2mail_create_job. It does not explicitly contrast with the nearest sibling click2mail_list_project_jobs, so the agent must infer which grouping 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?

Use is only implied: an agent can infer this is for fetching jobs belonging to one integration label. There is no explicit statement of when to prefer this over click2mail_list_project_jobs or click2mail_list_projects, and no prerequisites or exclusions are given.

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

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

Annotations already declare readOnly=true, destructive=false, openWorld=true, so the safety profile is covered. The description adds useful workflow behavior: it is a project-scoped lookup that requires a project name sourced from list_projects, and it names the fields returned. It doesn't mention pagination limits, but the schema covers that.

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

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

Two compact sentences: purpose plus returned fields first, then the prerequisite and endpoint. No padding, though the raw endpoint path is arguably low-value for an agent selecting the tool.

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

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

With no output schema, the description helpfully names the returned fields (id, status, description), and annotations handle safety. Pagination behavior and the distinction from other job-listing tools are left implicit, but nothing essential for a correct call 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%, so offset, project_name and number_of_jobs are fully documented in the schema; baseline is 3. The description adds a small hint that project_name should come from click2mail_list_projects, but gives no meaning for offset/number_of_jobs 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?

Clear verb+resource: 'List the mailing jobs of one project', with the returned fields (id, status, description) called out. It doesn't differentiate from sibling click2mail_list_jobs_by_app_signature or click2mail_list_jobs, and the phrase 'this is how to see the account's jobs' is slightly misleading since the scope is one project, not the account.

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: pick a project from click2mail_list_projects first, implying this is a follow-up drill-down tool. No explicit exclusion against the alternate job-listing sibling (list_jobs_by_app_signature), so it stops short of full when/when-not guidance.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile needs no restating. The description adds behavior the annotations do not: results are scoped to the account, ordered most-recently-updated first, and jobs without a project are grouped by month (e.g. "March 2022"). It also names the underlying endpoint GET /molpro/projects, leaving only pagination behavior undefined.

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, both earning their place: the first defines the resource, ordering and grouping rule; the second routes to the follow-up tool. The core purpose is front-loaded, 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 read-only, two-parameter list tool with 100% schema coverage and existing annotations, the description supplies everything an agent needs: scope, ordering, what a project is, the endpoint, and the next call. No output schema is needed, because the description already characterizes the shape of the results (named project groups).

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

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

Both parameters (offset, number_of_projects) are fully documented in the schema at 100% coverage, with ranges and paging advice, so the description need not repeat them. It adds nothing about paging or result limits beyond the schema, which is the expected baseline of 3 when the schema carries the burden.

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 definition names a specific verb and resource ('List the account's projects') and directly explains what a project is (a grouping of jobs, with month-based fallback groups). It also names the follow-up sibling click2mail_list_project_jobs, so an agent can distinguish this list tool from the jobs listing without opening either 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?

'Use a project name with click2mail_list_project_jobs' explicitly states the follow-up step, giving clear context for why you would call this tool. It does not, however, say when to prefer this over sibling listers such as click2mail_list_jobs_by_app_signature, so it earns a 4 and not a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds that this is a GET against /molpro/account/addresses and that results carry ids. It does not disclose pagination behavior, whether an empty list is possible for a valid type, or what happens with an unrecognized address_type.

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

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

One sentence plus the endpoint, with the payload description front-loaded and the actionable id-consumption hint immediately after. Nothing is padded or repeated.

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 single-parameter, non-destructive read with no output schema, the description supplies purpose, returned content (addresses with ids), and the workflow tie-in to job creation. There is no meaningful gap remaining for an agent to call it correctly.

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

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

Schema coverage is 100% and the single required parameter is fully documented in the schema, so the baseline is 3. The description's inline type list duplicates the schema examples but uses looser phrasing ('return addresses' vs. the schema's 'Return Address'), which could nudge an agent toward a non-matching string rather than clarifying accepted values.

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 resource (account addresses of one type) and enumerates what a returned record contains (address + id), which distinguishes it from sibling list tools like list_documents or list_projects. It never explicitly names a sibling it is not, so differentiation is by subject matter rather than direct routing.

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

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

Gives a concrete downstream use: 'use an id as `return_address_id` when creating a job,' which tells the agent why it would call this before click2mail_create_job. It does not address exclusions or overlap with click2mail_check_addresses or click2mail_get_address_list_info, leaving the boundary with those siblings implicit.

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

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

Goes well beyond the annotations: it discloses that the operation is free, that nothing is mailed or charged, that rendering takes a moment (latency), and that the reply names the proof — critical context for a non-idempotent write that produces no output 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?

Four short sentences, front-loaded with the WRITE classification and the core action, then cost, latency, and reply shape. The endpoint path is the only extra and is genuinely useful for mapping to the HTTP API.

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 single-parameter write tool with no output schema, the definition covers the action, cost/side effects, latency expectation, and response shape. Nothing an agent needs to invoke it correctly 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?

Only one parameter exists and schema coverage is 100% with a clear description ('Click2Mail job id (a draft)'). The prose's 'draft job' phrasing reinforces the constraint but 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?

The description opens with a specific verb and resource ('render a proof (preview PDF) of a draft job') and constrains it to draft jobs. It also implicitly separates this from submission siblings by stating 'nothing is mailed or charged', so an agent can tell it apart from click2mail_submit_job.

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

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

Usage is implied by 'draft job' and the free/no-mail caveat, which hints this belongs before submission. However, it never explicitly says when to use this vs. click2mail_submit_job, get_job_status, or get_job_info, nor when not to request a proof.

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description adds the crucial economic and physical consequences: postage and printing are charged to either prepaid credit or invoice, and real mail goes to every recipient. It further discloses the irreversibility nuance beyond the flat destructive flag — Invoice jobs can be cancelled pre-processing, User Credit jobs cannot.

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 risk warning, then purpose, then preconditions, then cancellation limits, then endpoint. Every sentence carries operational weight, and the repeated confirm reminder earns its place as a safety-critical gate rather than 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 three-parameter, high-consequence mutation with full schema coverage and no output schema, the description supplies everything an agent needs: cost implications, approval protocol, irreversibility conditions, and billing-mode consequences. Nothing material is left to inference.

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

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

Schema description coverage is 100% and all three parameters are documented, including the billing_type enum semantics and the confirm const constraint. The description restates '`confirm` must be true' but adds no new 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 and resource ('submit a draft job for printing and USPS mailing') and immediately distinguishes it from sibling creation/read tools like click2mail_create_job, get_job_cost and get_job_status. The lead-in 'WRITE, SPENDS MONEY, NOT REVERSIBLE' makes the operation class unambiguous at a glance.

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

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

Explicitly prescribes prerequisites ('read click2mail_get_job_cost and click2mail_get_credit') and the approval gate ('get the user's explicit go-ahead for this job and amount', '`confirm` must be true'). It also states the cancellation boundary (Invoice only, before processing), which tells the agent when this action cannot be undone.

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=false, destructiveHint=false and openWorldHint=true, and the description reinforces this with 'Creates data only; nothing is mailed or charged', which materially reassures the agent about cost and side effects. It does not mention that document_name must be unique (only in the schema) or that repeated calls are non-idempotent, so a few behavioral gaps remain.

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

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

Four short sentences, front-loaded with the operation class and purpose, with the scope caveat and return value following in order of importance. No filler and the endpoint is a useful trailing detail.

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?

There is no output schema, yet the description states the return value (document id) and its consumer, plus the cost and mailing side-effect boundaries. Combined with a fully described 4-parameter schema, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so every parameter is already documented, and the description only restates that the URL must be public http(s). It adds no format, size, or class/format pairing guidance 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 and resource: fetch a file from a public URL and store it as an account document. It also contrasts implicitly with click2mail_list_documents by describing creation rather than listing, and the leading 'WRITE:' tag makes the mutation class immediately legible.

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

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

The description names the downstream consumer ('Returns the document id for click2mail_create_job'), which tells the agent this is a prerequisite step for job creation. It does not state when NOT to use it (e.g. re-uploading an already-listed document), so it stops short of full when/when-not guidance.

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