Apply2Volunteer

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

Annotations cover safety (readOnlyHint=false, destructiveHint=false, openWorldHint=false) but not the operational semantics the description supplies: required credentials/scope, error behavior for unknown, expired, or cross-organization previews, and the idempotent replay guarantee that re-claiming returns the same draft. This is substantive context the structured fields do not carry.

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?

Six dense sentences, front-loaded with the action and credential requirement, followed by API mapping, parameter origin, return values, and failure/passivation behavior. No sentence is filler and nothing is buried.

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 mutation tool with an output schema and full annotation coverage, the description covers credentials, error modes, idempotency, and even names the return fields. An agent has everything needed 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 description coverage is 100% and the single parameter's derivation (previewId as the token in previewUrl /tools/p/{previewId}) is already stated in the schema. The description restates the same information with no added format or edge-case detail, 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?

States a specific verb and transformation: save an unexpired anonymous preview into the authenticated organization as a draft. This clearly separates it from siblings like get_preview (read), discard_form (delete), and preview_volunteer_form (render), so an agent can route 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 concrete preconditions (org API key or OAuth with forms:write scope) and precise failure conditions (unknown/expired preview is an error, preview already saved by another org is refused). It stops short of naming which sibling to use instead when the preview is already claimed or when the goal is just to view it.

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, so the description's real added value is the auth requirement (org API key with forms:read scope) and the fact that this persists a stored preview with an expiry. It could say more about what happens on re-conversion or expiry, but the key behavioral context is present.

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 leading with the action, then the prerequisite, then the alternative routing. No filler and every sentence carries information an agent needs.

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?

An output schema exists, so return-value detail is not the description's burden, yet it still flags the preview id and expiry. With annotations covering safety and the schema covering the parameter, nothing needed 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% for the single url parameter, which the schema already documents as an https URL of a blank volunteer PDF. The description restates 'PDF URL' without adding format, size, or validation constraints beyond what the schema provides, 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?

States a specific verb and resource (convert a PDF URL into a stored preview) scoped to the authenticated organization, which distinguishes it from generic PDF-adjacent siblings like create_form_from_pdf. It explicitly names preview_volunteer_form as the related-but-different tool, so the agent can route 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 the prerequisite (org API key with forms:read scope) and an explicit alternative with its selecting condition: use preview_volunteer_form when no key is available. That is a clear when/when-not/alternative statement rather than an implied usage note.

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

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

Annotations only declare the safety profile (write, non-destructive, closed-world); the description layers on the details an agent actually needs: auth scope, the 60-creates-per-org-per-hour rate limit shared across channels, Workers AI staying off, error behavior for unknown templates, and the 200-character title cap.

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?

Dense but front-loaded: identity and auth first, then behavior, limits, errors, and return value. Every clause carries information, though the run-on comma-heavy prose could be trimmed slightly for scanability.

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-optional-param mutation tool, it covers auth, defaults, template semantics, error cases, rate limits, and side effects. Return values (formId, editorUrl) are restated despite an output schema existing, but nothing an agent needs to call this 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?

With 100% schema coverage the baseline is 3, and the description adds real meaning beyond the schema: it specifies the default title resolution ('Volunteer application unless title is set') and that a template 'seeds that template's fields instead, using the on-server parser,' clarifying the interaction of the two optional params.

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 with scope: 'Create a blank draft form in the authenticated organization.' It pins down what 'blank' means ('no conversion, report, or preview is sent', default fields First name and Email), which implicitly separates it from create_form_from_pdf and preview_volunteer_form without the agent opening any 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 clear context: requires an org API key or OAuth with forms:write, template is optional, and an unknown template is an error. It also states what it does not do ('Does not publish the form'), routing the agent to publish_form. It stops short of explicitly naming sibling tools such as create_form_from_pdf as the alternative when a PDF is available.

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

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

Annotations only cover the read/write/destructive/open-world tri-state, but the description adds auth requirements (forms:write scope), a processing constraint (on-server parser only, Workers AI off), the side-effect boundary ('Does not publish the form'), and a data-handling guarantee ('File contents are not logged'). That is exactly the extra behavioral context annotations cannot carry.

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?

Five short sentences, front-loaded with the action and scope, with no filler. The only minor slack is restating the return values (formId, editorUrl) when an output schema already exists.

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?

Annotations cover safety, the output schema covers return shape, and the description covers auth, processing path, and side effects, so an agent has what it needs to invoke correctly. The remaining gap is sibling disambiguation, which 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 both parameters are already documented in the schema, so the description neither needs to nor does add syntax or format detail. 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+resource pair ('fetch a PDF or page URL and save a draft form') plus scope ('in the authenticated organization'). It also orients the agent relative to siblings by likening the behavior to claim_preview and explicitly noting it does not publish, which separates it from publish_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?

Provides real prerequisite context ('Requires an org API key with forms:write scope') and states the operation only creates a draft, but never names an alternative or exclusion condition. An agent choosing between this, create_form, preview_volunteer_form, and convert_pdf_preview gets no routing rule.

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 names the auth requirement (org API key or OAuth with forms:write), states exactly what is destroyed (the draft and drafted public settings) versus preserved (the published form), and documents return shapes plus 404/409 semantics. The destructiveHint=true annotation is fully consistent with the described 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?

Front-loaded with purpose and auth, then layered with semantics and error cases. Mostly dense, though the sentence enumerating what counts as 'no open draft' is somewhat redundant with the preceding definition.

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 an output schema present, the description need not detail return values, yet it still supplies the key error contracts, auth scope, and non-destructive-to-the-form clarification. Nothing needed to invoke this 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% so the formId param is already documented, but the description adds real meaning: the id must belong to the authenticated organization, and a form from another organization resolves as not found rather than erroring differently.

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 ('Discard the open draft of a form') and defines the scope ('belongs to the authenticated organization'). It also preempts confusion with a delete-shaped sibling by explicitly saying 'This does not delete the form', and defines what an 'open draft' is.

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 for when the tool succeeds and when it fails: a form with no open draft returns 404, and a stale read returns 409. It does not explicitly contrast with siblings like publish_form or update_form, so it stops short of full alternative routing.

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

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

Beyond the annotations (which already cover read-only, idempotent, closed-world), it discloses the auth model (no API key for public ids; org API key or OAuth token with forms:read for form:<id>), the complete not-found surface (draft, archived, deleted, unknown id, other organization), and a privacy guarantee that applicant data is excluded. This is exactly the kind of context annotations cannot express.

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?

Purpose and the id-provenance rule are front-loaded, and most sentences carry distinct information. The trailing 'Workers AI stays off' is opaque jargon that does not clearly earn its place, and the auth clause interrupts the otherwise consistent content description.

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 read tool with an output schema, the remaining burdens are auth, failure modes, and payload contents, and all three are addressed. Return fields are enumerated anyway (id, title, text, url, metadata, trialUrl), so an agent has nothing left to guess about before calling.

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 prefix conventions are already documented and the baseline is 3. The description still adds real meaning by tying the id to a prior search result and by attaching a distinct authorization consequence to the form: prefix, which the schema does not state.

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

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

The first sentence names a specific verb and resource ('Read one document') and scopes it to the id returned by search. It also distinguishes the payload from the sibling get_form ('metadata includes the same share links as get_form'), so an agent can tell the two apart 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?

It establishes the entry condition (the id must come from a prior search hit) and enumerates which id namespaces are eligible (doc:, template:, form:). It stops short of explicitly saying when to prefer get_form over fetch despite noting the metadata overlap, so routing between the two is still partly inferential.

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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new context beyond annotations: the org-membership constraint and the required org API key with applications:read scope. It does not say how out-of-org or missing-scope calls fail, which is a minor remaining gap.

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 with no filler; the core action and the org-scoping qualifier are front-loaded, and the auth requirement follows immediately. Every clause earns its place.

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

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

For a single-resource read tool with one fully documented parameter, an output schema, and rich read-only annotations, the description covers the one thing the structured fields do not: the scope/organization constraint and credential requirement. Nothing an agent needs 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?

There is a single required id parameter with 100% schema description coverage, so the schema already carries the documentation burden. The description's 'by id' phrasing adds no format, source, or validation detail beyond what the schema states, making the 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?

States a specific verb and resource ('Get one application by id') and adds a scoping constraint (must belong to the authenticated organization). It does not explicitly distinguish itself from the similar-looking sibling get_form or explain its relation to list_applications, so sibling differentiation is left implicit.

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 clear use condition — retrieving a single application within the authenticated org — and states the required credential. It stops short of naming alternatives (e.g., use list_applications to discover ids) or stating what happens for ids outside the org, so no explicit when-not guidance is present.

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, idempotent, and non-destructive, so the safety profile is covered. The description earns credit for adding auth requirements (org API key with forms:read scope) and the conditional presence of publicUrl/publicFormUrl/embedUrl/embedSnippet based on published/soft-deleted state, which structured fields do not 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?

Front-loaded with the core action, then auth, then return-shape conditions. Three sentences all carry information, though the trailing "omits those fields too" repeats the prior clause and could be tightened.

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 (one required id, output schema present), so return values need not be re-explained, yet the description still covers ownership scoping, auth scope, and conditional field behavior. 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?

Schema coverage is 100% for the single id parameter, so the baseline is 3. The description adds meaning beyond the schema by constraining the id to a form owned by the authenticated organization, clarifying the lookup semantics.

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 one form by id") and scopes it to the authenticated organization. An agent can immediately distinguish this from list_forms and the mutation siblings like update_form or discard_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?

Gives clear conditions for use: the form must belong to the authenticated org and the caller needs an org API key with forms:read scope. It does not explicitly name alternatives (e.g., list_forms for enumeration), so it stops short of full when/when-not routing.

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 (readOnly, idempotent, non-destructive), and the description adds real value beyond them: no API key required, the exact returned fields, the /tools/p/{previewId} public page correspondence, the not-found behavior including the converter URL, and an explicit statement that org ids and saved form ids are withheld.

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

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

Three sentences, zero filler, with the core operation and the no-API-key note front-loaded. It is slightly dense with return-field enumeration that the output schema already carries, but nothing is wasted or buried.

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 read tool with full annotation coverage and an output schema, this description covers authentication, error behavior, scope boundaries, and return 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?

Schema description coverage is 100% and the single previewId parameter is fully documented in the schema, including the pattern and its source in previewUrl. The description restates the same origin, so it adds no syntax or format detail beyond the schema — baseline 3 is correct.

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 (read a converter preview) scoped by previewId, and the 'unexpired' qualifier plus the claim-status note distinguish it from the sibling claim_preview. An agent can tell what this returns 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?

Makes clear this reads an existing preview whether or not it was claimed, which implicitly routes claiming to claim_preview, and notes unknown/expired ids are not found. It stops short of naming claim_preview as the alternative for the write path or stating prerequisites explicitly.

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 readOnly/openWorld annotations: discloses that only the on-server grader is used (Workers AI and other models stay off), that restricted fields like SSNs are excluded from parsing but still counted in scoring, and details three separate rate-limit regimes (anonymous 5/network/day, daily anonymous MCP cap, org hourly limit with forms:read). This is exactly the kind of auth, cost, and constraint context annotations cannot carry.

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?

Purpose is front-loaded in the first sentence, followed by output shape and then limits in rough priority order. It is dense but nearly every sentence carries non-redundant information; the only blemish is the garbled clause 'left out of parsed'.

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?

An output schema exists, yet the description still names the key return fields (score, letter grade, fixes, reportUrl share page), covers input exclusivity, privacy handling, and all applicable rate limits. 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?

Schema coverage is 100% and both parameters are documented there, including the oneOf mutual exclusion. The description's 'url or text, not both' restates what the schema already enforces, adding no format or semantic detail beyond it, 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 ('Grade a blank volunteer form') plus the two supported input modes (pasted text or document URL). It explicitly scopes itself against a sibling concept with 'Does not grade a saved form', so an agent can distinguish it from get_form/update_form without opening schemas.

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 usable context: 'Send a url or text, not both', 'No API key', and the exclusion 'Does not grade a saved form.' It stops short of naming an alternative sibling (e.g. preview_volunteer_form or get_form) for the saved-form case, so routing is inferred rather than explicit.

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 (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description usefully adds the authentication requirement and the exact scope needed, which is real behavioral context an agent cannot get from the annotations or 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?

Two short sentences, front-loaded with the core action and scope, followed by the auth prerequisite. Every sentence carries information; nothing is redundant or padded.

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?

An output schema exists, so return values need not be described. With the single parameter documented, safety covered by annotations, and the auth/scope requirement spelled out, an agent has everything needed to select and invoke this tool correctly.

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

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

Schema coverage is 100% and the single formId parameter is documented in the schema. The description's phrase 'for one form' is consistent with the schema but adds no format, source, or constraint detail beyond it, 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 ('List applications') and constrains scope to 'one form in the authenticated organization'. It contrasts implicitly with the singular get_application sibling, but never names or distinguishes an alternative 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?

The description supplies a concrete prerequisite (an org API key with the applications:read scope), which implies this is the org-scoped listing path. However it gives no explicit when-to-use guidance versus get_application or other listing tools, leaving the agent to infer.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds real context: the required org API key and forms:read scope, plus the state-dependent presence of publicUrl/publicFormUrl/embedUrl/embedSnippet for published vs draft vs soft-deleted forms.

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 purpose then auth then field behavior; every sentence carries information. The last two sentences about omitted fields could be merged, 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 parameterless read tool with an output schema, the description supplies everything not already structured: the auth scope and the conditional-field rules that explain why some items look sparser.

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 and schema coverage is 100%, so the baseline is 4. There is no parameter syntax the description could usefully add.

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) and resource (forms) and scopes it precisely to 'forms that belong to the authenticated organization,' which separates it from the single-record sibling get_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?

Usage is implied by the org-scoped framing, but the description never says when to pick this over alternatives like get_form or list_applications, nor any exclusions such as archived workspaces. Adequate but leaves routing 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?

Goes well beyond the annotations: on-server parser only with no Workers AI/model charge, parsed form kept 24 hours then deleted by daily cleanup, URL fetched exactly once, file contents not logged, restricted fields like SSNs excluded, and anonymous per-network plus daily caps. With annotations only declaring write/open-world and non-destructive, this description carries substantial extra behavioral context.

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?

Purpose is front-loaded and most sentences carry unique facts (storage lifetime, privacy, rate limits). Minor waste and repetition around the sign-up link, which appears twice ('sign up free to publish', 'over the cap, sign up free'), and the return-field enumeration is partly redundant with the output schema.

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

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

For a tool that writes stored state and returns URLs, the description covers input exclusivity, privacy handling, retention, rate limits, and the nature of the returned links; with an output schema present, it need not explain return values further. An agent has everything required to call it and set expectations.

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 oneOf exclusivity and all three parameter descriptions already exist in structured form; the prose restates 'send exactly one of url, text, or template' without adding syntax or format detail 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?

States a specific verb and resource ('Convert a blank volunteer application into an online form preview'), and the word 'preview' plus 'blank' scopes it away from write tools like create_form or publish_form. However, it never names a sibling explicitly, so the agent must infer the boundary with convert_pdf_preview, create_form_from_pdf, and get_preview.

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 useful gating context ('No account and no API key', rate limits, 'over the cap, sign up free') and input-shape rules, but never says when to pick this over create_form or get_preview, nor when a preview should be followed by claim_preview/publish_form. Usage is implied rather than directed.

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 (readOnlyHint=false, destructiveHint=true, openWorldHint=false) by disclosing auth scope requirements, the specific validation checks run, the 400 rejection for a form with no fields, and the 409 conflict when publishing would drop a field key that already has answers or consents. This explains exactly what the destructive hint means in practice.

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 action and auth requirement, then error behavior and return values in a logical order; every sentence carries information. It is on the dense side but not padded with filler.

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

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

For a one-parameter mutation with an output schema, the description covers auth, preconditions, failure modes with exact status codes and messages, and cross-organization restrictions. Although the output schema exists, enumerating the returned fields is harmless reinforcement and nothing an agent needs 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 description coverage is 100% and the single formId parameter is already documented as a draft in the authenticated organization, so the schema does the work. The description restates the same constraint without adding format or syntax detail, making the 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?

States a specific verb (publish) and resource (draft form) plus the scope constraint that the form must belong to the authenticated organization. The state transition from draft to published is unambiguous and cannot be confused with siblings like update_form, create_form, or discard_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?

Gives clear preconditions: an org API key or OAuth sign-in with the forms:write scope, and a draft owned by the authenticated org. It does not explicitly name alternative tools or say when not to use this one, but the draft-only scoping implies the usage context well.

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

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

Beyond the readOnly/idempotent annotations, it discloses concrete behavioral traits: a 20-hit cap, exclusion of drafts, archived and deleted forms, exclusion of other organizations, and exclusion of applicant PII (names, emails, answers, notes, consents). That is exactly the kind of data-boundary and result-shape context 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?

Scope and limits are front-loaded and each sentence carries operational meaning. Minor waste from repeating the 200-character limit and empty-query behavior already present in the schema.

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 search tool, everything needed to call it correctly is present: input limits, result cap, field shape, exclusion rules, and the credential-dependent behavior change. The output schema exists, so the brief field enumeration is a convenience rather than a burden.

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 maxLength 200 and the empty-string behavior are already documented in the schema; the description largely restates them. It adds the useful nuance that case does not matter for matching, but otherwise defers to the schema, which is the expected baseline.

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 ("Search public Apply2Volunteer documents by keyword") plus the access scope (public, no API key), which separates it from siblings like list_forms, get_form, and fetch. It also names the extended behavior when an org credential is supplied, so an agent can tell exactly which slice of content this tool covers.

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 operating conditions: no API key required, empty query yields no results, and an org key/token widens matching to that org's live published forms. It does not explicitly say "use list_forms to browse" or exclude any sibling by name, so routing guidance is strong but not fully explicit.

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

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

Annotations already indicate this is a non-read-only, non-destructive, non-open-world operation. The description adds important behavioral context beyond the annotations: it requires an org API key with the applications:write scope, mandates a decline reason when status is declined, and explicitly clarifies that it does not delete the application. It does not address transition rules or idempotency, 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?

The description is four short sentences with no wasted words. It front-loads the core action, then adds permission, conditional logic, and non-deletion clarification in a logical order. Every sentence contributes useful information.

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

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

The tool has an output schema and annotations, so return values and safety hints need not be explained in the description. The description covers authorization, the key conditional requirement, and the non-destructive nature of the operation. It could be more complete by mentioning valid status transition constraints or side effects, but it is sufficient 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 67%, so the schema already documents id and declineReason to some extent, and the status enum values are self-describing. The description adds meaningful conditional semantics for declineReason when the status is declined, which is not fully captured by the schema. It does not add further detail about the id parameter or status transition meaning beyond the enum.

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: setting an application's status. It also scopes the operation to the authenticated organization, which distinguishes it from sibling tools like get_application and update_form. An agent can identify exactly what this tool 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?

The description implies when to use it by explaining it writes status and does not delete the application. However, it does not name a specific alternative tool or state clear conditions for choosing this tool over siblings such as get_application or update_form. The guidance is useful but not comprehensive.

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?

Far beyond the three hint annotations, the description discloses auth/scopes, cross-org isolation ("belongs to another organization is not found"), a 60-updates-per-organization-per-hour shared limit, the full 409 catalogue (occupied order, field with answers/consents, key change refused, stale field id), caps (20 add/20 remove per call, 140 fields/form), __-prefixed settings keys being ignored, and editorSeq last-write-wins semantics. Side effects of the removal path are spelled out, and the draft-only, data-protecting constraints make the delete behavior consistent with destructiveHint=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?

Purpose, auth, and the PATCH-equivalence are front-loaded, and the length is largely justified by the tool's many constraints (limits, id rules, 409 conditions). It loses a point for repeating schema content nearly verbatim (order semantics, op add requirements, removeFieldIds behavior) that the input schema already carries.

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 complex mutation with nested objects, 7 parameters, and an output schema, the description covers everything an agent needs: identity/scope, required scope, insert vs update vs delete semantics, quotas, conflict handling, and recovery guidance. Return values are already handled by the output schema, so no gap remains.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds real meaning the schema does not fully convey, such as stageId defaulting to the Interest or first stage, the server assigning new field ids, order being ignored on inserts, and the error semantics for order collisions and unknown field ids. It does, however, restate much of what the nested schema fields already document.

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?

"Update a form that belongs to the authenticated organization" gives a specific verb plus resource and an explicit tenancy scope. It also distinguishes itself from siblings by naming get_form as the re-read path and stating "Does not publish the form," which separates it from publish_form/create_form 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?

Usage context is strong: it names the auth requirement (org API key or OAuth with forms:write), tells the agent to re-read with get_form and retry on stale field ids, and clarifies it never publishes. It stops short of explicitly stating when to prefer create_form, discard_form, or publish_form instead, so exclusions are implied rather than enumerated.

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