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

With no annotations, the description carries the full burden and does deliver real behavioral context: the token is a credential, is never logged nor echoed in errors, and success is a 200 with an empty body. It stops short of saying whether activation is idempotent, reversible, or what failure responses look like (e.g., expired token), which keeps it from a 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?

Three short sentences, front-loaded with the core action, then the security constraint, then the return shape. No filler or repetition. Slight disjointedness between the credential and return-value sentences, but size is appropriate.

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 spelled out (though the empty-200 note is a helpful bonus), and the fully-described schema covers parameters. What is missing for a mutation tool with no annotations is any statement of prerequisites or side effects of activation, which prevents a 5.

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

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

Schema description coverage is 100%, so the schema already documents all three required parameters, giving a baseline of 3. The description adds only marginal meaning for 'token' (it authorizes activation for the named project), which the schema already conveys, and says nothing extra about form_id or project_name.

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 ('Activate') and resource ('Educloud for a form'), which is far better than a tautology. It does not explicitly distinguish itself from the sibling 'activate_tsd', but the Educloud-vs-TSD distinction is inferable from the name and body. Clear, if not sibling-explicit.

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 never states when to use this tool, what prerequisite state a form/project must be in, or how it relates to the sibling 'activate_tsd'. An agent must guess whether this is a one-time setup step or a repeatable operation. No exclusions or alternatives are offered.

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

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

With no annotations, the description carries the full burden, and it does disclose two genuinely useful facts: the token is a sensitive credential never logged or surfaced in errors, and success returns 200 with an empty body. It omits idempotency behavior, what happens if TSD is already active, required permissions, and error semantics, so coverage is partial rather than rich.

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 paragraphs, front-loaded with the action and resource, each sentence carrying distinct information (purpose, credential handling, response contract). No filler, though the credential paragraph 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?

It covers the credential contract and success response, and an output schema exists so return values need not be re-explained. It still leaves the relationship to the sibling activate_educloud, preconditions, and failure modes unaddressed for a mutation tool with no annotations.

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 baseline is 3, but the description adds meaning beyond the schema by explaining that the token is a credential authorizing activation for the named project and must be protected like an OAuth2 access token. That materially clarifies the token's role and handling beyond its one-line schema description.

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

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

States a specific verb (Activate) and a specific, unusual resource (TSD / Services for Sensitive Data) scoped to a form, which most agents would not confuse with generic form operations. However, it never distinguishes itself from the sibling 'activate_educloud', which appears to be a parallel activation path, leaving that differentiation to inference.

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

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

No when-to-use guidance is given: it does not say when TSD activation is required, what preconditions must hold, or how to choose between this and activate_educloud. The only contextual hint is that the token 'authorizes activating TSD for the named project', which is about mechanics, not selection.

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 readOnlyHint annotation already covers safety, but the description adds substantive behavioral facts the annotations cannot convey: no network request is made, it remains functional even when auth is broken, and the client secret is never returned (only whether it is set). That is exactly the extra context this dimension rewards.

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 first two sentences are tight, front-loaded, and earn their place. The trailing 'Returns:' block slightly duplicates the output schema, which the rubric says the description needn't restate, so it is not maximally lean.

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

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

For a zero-parameter diagnostic tool with an output schema, the description supplies the two things an agent actually needs to decide and act: that the call has no side effects on the API and that it is the right probe under auth failure. 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 per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it does not clutter itself with invented parameter guidance.

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 ('Report') and a specific resource ('which Nettskjema credentials and URLs this server is configured with'), which an agent can instantly distinguish from every sibling tool that actually calls the API. Nothing is tautological – it does not merely restate the name 'check_auth_status'.

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 clear conditional context: 'Makes no request, so it still answers when authentication is the thing that is broken' tells the agent to reach for this when auth failures are suspected. It does not explicitly name a sibling alternative (e.g., get_user_info as a live credential probe) or state exclusions, so it stops short of the top band.

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

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

No annotations exist, so the description carries the full burden. It does add genuine behavioral detail: the six settings are enforced as named parameters to prevent omission, and named parameters override duplicates in extra_settings. However, it omits permissions/auth requirements, validation or failure behavior, and what creation side effects occur.

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, front-loaded with the action and then the parameter mechanics. Each sentence carries information, though the rationale sentence ('so a model cannot omit them') is explanatory rather than operational.

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 no explanation, and the required-vs-extra_settings mechanics are covered. But for an 8-parameter creation tool with no annotations, the description lacks auth/permission context and gives no hint about element structure, leaving the agent under-informed about non-parameter aspects.

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 already 100%, so the baseline is 3, but the description adds real meaning the schema cannot: the interaction between the named required parameters and extra_settings, plus the explicit precedence rule. It does not explain enum values or element/extra_settings formats, leaving some room above.

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+resource ('Create a new form') and clarifies scope (settings plus optional elements), which distinguishes it from mutation siblings like update_form_settings or replace_form_elements. It does not explicitly name any alternative tool, so it stops short of full sibling 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?

Usage is implied by the creation verb, and there is useful guidance about how to supply parameters (named vs. extra_settings), but nothing states when to reach for create_form versus update_form_settings or duplicate/lookup tools. 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 only mark destructiveHint=true; the description goes well beyond that by stating the operation is irreversible, that no undo or trash can exists, that no id list or partial mode is offered, and that user confirmation is required. It even discloses a deliberate design decision (sending no body) so the agent understands why no limiting parameter exists.

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 destructive warning and scope are front-loaded in the first sentence, which is the right structure. The third paragraph on the spec's plural operation is longer than strictly needed to invoke the tool, though it does justify the missing parameter.

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 annotations covering destructiveness and an output schema covering return values, the description supplies exactly the missing context: irreversibility, blast radius, the alternative tool, and the confirmation requirement. Nothing an agent needs to call this safely is absent.

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 there is only one parameter, so the schema already carries the field semantics. The description adds value by explaining the absence of an id parameter and why it was not exposed, which is meaning beyond the schema itself.

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 full scope ('Delete EVERY response the form has ever collected') and explicitly distinguishes itself from the sibling delete_submissions, which handles id-scoped deletion. An agent can separate the two 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 explicit when-to-use ('the whole dataset goes'), when-not ('To remove particular responses, use delete_submissions'), and a prerequisite ('Confirm with the user before calling it'). Nothing 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 destructiveHint=true, so the safety profile is covered structurally; the description adds genuinely new context by disclosing soft-delete semantics (moved to trash, restorable for a limited time) and the point at which deletion becomes irreversible. It omits auth/permission requirements and response shape, but the trash-retention detail is real value beyond the annotation.

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

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

Three short sentences, front-loaded with the action and scope, then the recoverability caveat and the irreversibility window. Nothing is wasted, though the last sentence partially restates the destructive nature already flagged by 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?

An output schema exists and annotations cover the destructive flag, so the description only needs to add behavioral context — which it does via trash retention and irreversibility. It is close to complete for a one-parameter delete tool, with only auth/permission behavior left unaddressed.

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

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

Schema description coverage is 100% for the single form_ids parameter, and the description adds no format or syntax detail beyond what the schema already documents. Baseline 3 applies when the schema carries the parameter 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 description states a specific verb+resource (delete forms) and notes batch capability via 'one or more forms by their IDs'. It is clearly distinct from delete_submissions and delete_all_submissions by resource, but it never explicitly names a sibling or draw the boundary for the agent.

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

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

No when-to-use guidance and no alternatives named. The trash/retention detail implies recoverability but the description never tells the agent when this tool is the right choice versus the other delete_* siblings.

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, and the description adds substantial context beyond that: deletion is irreversible with no undo, only the listed ids are affected, and an empty list is refused rather than sent. This is exactly the kind of operational detail an agent needs for a destructive tool.

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 constraint and scoping, and every sentence carries information. The middle paragraph is slightly redundant, restating 'removes exactly the submissions whose ids are given, and nothing else' after the opening sentence already said it, but it is not wasteful overall.

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 two-parameter destructive tool with an output schema present, the description covers scope, irreversibility, sibling disambiguation, id sourcing, and the empty-input guard. 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%, so the baseline is 3, but the description adds useful meaning: submission_ids must not be empty, and it points to the tools that supply valid ids. It also reinforces the submission-id vs form-id distinction, though form_id itself is only covered by 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 (delete) plus resource (submissions/responses to a form) and immediately bounds the scope to 'ONLY the listed responses.' It also names the sibling it must not be confused with (delete_all_submissions), so an agent can distinguish it 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?

Explicitly says when to use it ('whenever specific responses are meant'), when not to (vs delete_all_submissions, which takes no id list), and where the required ids come from (get_submission_metadata or list_my_submissions). It even covers the empty-list edge case and why it exists.

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

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

With no annotations, the description carries the full burden and does so admirably: it discloses that output_path writes to disk with mode 0600 for new files (overwriting existing files while preserving mode), that omitting it returns JSON, that results are capped at max_chars with truncation at the last complete newline, and that a truncated flag signals cutting. These are exactly the mutation/side-effect facts an agent needs.

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

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

Front-loaded with the one-line purpose, then two coherent paragraphs covering the two output modes and the truncation cap. Slightly verbose in echoing schema details (mode 0600, ~ resolution) but every sentence is on-topic and earned.

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 clarifies return-shape behavior (path/bytes/mediaType vs JSON with size signal) and the truncation contract. For a 4-parameter export tool with no annotations, nothing material 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 coverage is 100%, so the baseline is 3, but the description adds genuinely non-schema information such as the semicolon delimiter of the CSV and the interaction between max_chars and output_path. The restating of defaults and path resolution overlaps the schema, keeping this from a 5.

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 and output format: 'Export a form's submission data as CSV.' This is clearly distinguishable from read tools like get_form_answers. However, it never differentiates from the close sibling export_form_excel, which an agent must choose between, so it falls 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?

The description explains the behavioral consequence of providing vs omitting output_path, which implicitly guides usage, but it never states when to pick this tool over export_form_excel or other export/read alternatives. Usage is implied rather than prescribed.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: streamed-to-disk rather than inlined, absolute tilde-expanded paths, silent overwrite of existing files, mode preservation, 0600 for new files, and the temp file's post-call lifecycle. These are exactly the destructive/permission details an agent needs and cannot get anywhere else.

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 paragraphs, front-loaded with the core action before the disk semantics. Every sentence carries substantive information; the density is high but nothing reads as 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?

An output schema exists, yet the description still covers the returned path semantics, and it fully compensates for the absent annotations on the write side. For an export-to-disk tool the agent knows the destination, the overwrite risk, and the file lifecycle 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 baseline is 3. The description goes beyond the schema by explaining the concrete consequence of omitting output_path (temp file in the system temp dir, suffix from media type) and the overwrite/mode behavior at that path; form_id and optimize_for_large_data gain nothing 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?

States a specific verb and resource ('Export a form's submission data to a file, written to disk') and identifies the output format as an Excel file, which implicitly separates it from the sibling export_form_csv without naming it. Slightly short of 5 because the alternative is never named outright.

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 useful operational context (what happens when output_path is omitted, where the temp file lands), but never states when to prefer this tool over export_form_csv or get_form_answers. Usage is implied by the format rather than explicitly routed.

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

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: it discloses silent overwrite of existing files, mode preservation, 0600 permissions on new files, absolute/tilde-expanded return paths, and that temp files persist after the call. These are exactly the destructive and side-effect details an agent needs before invoking.

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 in the first sentence, then organized into coherent paragraphs on path handling, overwrite/permission semantics, and temp-file behavior. Slight redundancy ('written to disk' restated as 'streamed to disk') keeps it from a perfect score.

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, and the remaining gaps an agent would care about (where the file lands, what happens to existing files, permissions, temp-file lifetime) are all covered. Nothing needed 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%, so the baseline is 3, and the description adds meaning beyond the schema by explaining why output_path is omitted (temp file in system temp dir with a suffix derived from the response media type) and by reinforcing the absolute-path return. It stops short of documenting invalid-id or failure behavior for the required ID.

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 ('Download an answer attachment to a file'), and the emphasis on streaming to disk rather than inlining distinguishes it from sibling read tools like get_image or get_submission_pdf that return different artifacts. An agent can identify the operation 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?

Usage is implied by the mechanics described (omit output_path for a temp file, supply it to control the destination), but there is no explicit when-to-use guidance and no routing to alternatives such as get_attachment_transcription or get_submission_pdf. The context is inferable but never 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 only cover readOnlyHint=true, so the description carries the rest and does so well: it discloses the transcription prerequisite, the max_chars truncation cap and its default, the truncated flag signal, and that the caller can raise the limit. It omits whether transcription is asynchronous or how long it may take, but the core behavioral traits are covered.

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 paragraphs, front-loaded with the purpose and formats, then preconditions, then the truncation caveat. The truncation paragraph partially duplicates the schema's max_chars description, but no sentence is 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?

An output schema exists, so return structure needn't be explained, and the description still flags the truncated field. Inputs are fully covered by the schema and the preconditions are stated, leaving only the no-transcription recovery path unaddressed.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including per-format meanings and max_chars semantics. The description largely restates the max_chars default and truncation behavior rather than adding new syntax or edge-case guidance, 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 (Get) and resource (attachment transcription) plus the three output formats. An agent can distinguish it from get_answer_attachment (the raw attachment) and retranscribe_attachment (generation), though neither sibling is named 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?

Clearly states the precondition — the attachment must have been uploaded with transcription options — and the negative case (file without transcription, or non-audio/video, has nothing to retrieve). It does not, however, route the agent to retranscribe_attachment when no transcription exists, which would be the natural alternative.

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

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

With readOnlyHint=true already declaring safety, the description goes well beyond annotations: it discloses the streaming NDJSON framing (one object per line), the default 1000-row cap, and the truncated/reason output contract including the 'rowCap' vs 'incompleteFinalLine' distinction. That is exactly the kind of operational behavior an agent needs to handle partial results correctly.

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 primary purpose is front-loaded in the first sentence, followed by progressively finer detail on framing, filtering, and truncation. It is dense but each clause carries information; only the NDJSON restatement is mildly 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?

An output schema exists, so return values need not be described, yet the description usefully explains the truncated/reason fields an agent must branch on. Combined with full schema coverage and a readOnly annotation, this is sufficient for a streaming read tool; only the sibling-export distinction is left unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents form_id, max_rows, element_ids, and the rest in detail. The description largely restates those semantics (filter via element_ids, cap via max_rows) rather than adding new syntax or interaction detail, 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 opening sentence states a specific verb (stream/export) and resource (all answers for a form) plus the exact wire format (newline-delimited JSON). It is unambiguous about what the tool produces. However, it does not differentiate itself from sibling exporters like export_form_csv or export_form_excel, which also export form answers, leaving the agent to infer the difference from format alone.

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

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

Usage is implied rather than stated: the note that answers are 'never held whole in memory' and the max_rows cap signal this is the choice for large-form streaming, and element_ids is offered for question-scoped exports. But there is no explicit when-to-use versus the CSV/Excel export siblings, and no stated prerequisites or exclusions.

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

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

readOnlyHint=true already establishes this is a safe read operation, so the description carries a lighter burden. However, it adds no behavioral context beyond annotations — no indication of whether it reflects the latest form version, whether history is complete, or any access restrictions. Describing the return payload adds little since an output schema already exists.

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

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

A single efficient sentence that front-loads the core purpose and then enumerates the payload. No filler or redundancy, though it is terse to the point of omitting routing guidance.

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 read-only tool with full schema coverage and an output schema, the description is minimally sufficient — return values need not be explained. The gap is the failure to distinguish this tool from the many overlapping form-retrieval siblings.

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 there is a single parameter (form_id) documented as 'The form's numeric ID.' The description adds no semantics beyond the schema, so the baseline of 3 for high coverage 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 names a specific verb ('Get') and the resource content ('the form's structure and creation history'), specifying the elements array and authorship metadata as the payload. It is clear what the tool returns, but it does not distinguish itself from close siblings like get_form_elements or get_form_info, which appear to overlap heavily.

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

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

There is no guidance on when to use this tool rather than get_form_elements, get_form_info, or get_form_settings, all of which are plausible alternatives for retrieving form data. The agent must infer the distinction from the name 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?

readOnlyHint=true already tells the agent this is a safe read, so the description earns credit for going further: it discloses that the corresponding write is a full-list replacement, which is the key behavioral trait driving the read-modify-write pattern. It says nothing about ordering guarantees or size limits, but the output schema covers the return shape.

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: what it returns first, then when and why. Nothing is wasted, and the workflow constraint is front-loaded rather than 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?

With a single well-documented parameter, an output schema covering the return value, and readOnlyHint covering the safety profile, the description supplies exactly the missing pieces: the element taxonomy and the destructive-replace context needed to use the result correctly.

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

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

Only one parameter (form_id) and schema_description_coverage is 100%, so the schema fully documents it as 'The form's numeric ID.' The description adds no format, source, or lookup guidance for the ID, so baseline 3 is the right call.

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 the form's elements') and enumerates exactly what those elements are: questions, headings, images, page breaks. That enumeration scopes it well against adjacent readers like get_form_definition or get_form_info, though it never names a sibling explicitly, which keeps it just 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?

'Use this before any element edit' gives an explicit trigger condition tied to the edit workflow, and it explains why the read is needed (the write endpoint replaces the whole list). It does not name replace_form_elements/update_form_element as the alternatives or state when this tool is unnecessary, so a small inference gap remains.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context. It clarifies the exact metadata returned (counts, status, permissions), which is useful, but says nothing about permissions needed or freshness/staleness of the counts.

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

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

A single tight sentence that front-loads the verb and lists the payload in order. No filler, though the field enumeration makes it slightly list-like.

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 format need not be described, and the read-only annotation covers safety. Combined with a fully documented single parameter, the definition is nearly complete; only sibling routing 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% with a single form_id param fully documented, so the description carries no additional parameter burden. Baseline 3 applies since the schema does the explanatory 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 (Get) and resource (form) and enumerates the returned metadata: submission counts, open/closed status, edit permissions. However, it does not distinguish itself from close siblings like get_form_settings, get_form_definition, or get_form_settings_validation, which an agent must choose between.

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 or when-not condition, and no alternative is named despite many read-oriented sibling tools. The enumerated return fields only implicitly suggest the tool's scope.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the useful fact that the result is a full settings bundle (51 settings covering behavior and permissions), but says nothing about permission requirements or whether the payload differs between the normal and create-form modes.

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

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

A single front-loaded sentence with no filler; the verb and resource lead and the scope detail follows immediately.

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

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

An output schema exists, so return values need not be explained, and the read-only nature is annotated. What is missing is routing context: without any mention of get_form_settings_validation or update_form_settings, the definition is adequate but does not fully equip an agent to pick among the settings-related siblings.

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

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

Schema description coverage is 100%, so the schema already fully documents both form_id and is_for_create_form. The description adds no syntax or format detail beyond the schema and notably ignores the is_for_create_form mode entirely.

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 the form's configuration") and quantifies the payload (51 settings controlling behavior and permissions), which is more concrete than the bare name. However, it never distinguishes itself from close siblings like get_form_settings_validation or update_form_settings, so the agent must infer the difference from the name alone.

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

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

No when-to-use guidance is provided. The description does not say whether this is the read counterpart to update_form_settings, how it relates to get_form_settings_validation, or when get_form_info would be preferred 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?

readOnlyHint=true already tells the agent this is a safe read, and an output schema exists, so the bar for additional context is low. The description nonetheless adds nothing behavioral — no note on whether it validates on demand or reports stored results, and no scope/side-effect detail beyond the annotation.

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

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

A single front-loaded sentence with no wasted padding. The only flaw is the imprecise 'errors or constraints' disjunction, which is a precision issue rather than verbosity.

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 readOnlyHint set and an output schema present, the return values need not be described, so the definition is minimally workable. What is missing is sibling differentiation and a clear statement of what 'validation' means here, leaving the tool under-explained relative to the crowded form-settings toolset.

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 with 100% schema description coverage ('The form's numeric ID'), so the schema does the documentation work. The description contributes no extra parameter meaning, which is the expected baseline at high 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?

The verb+resource ('get ... form's settings validation') is identifiable, but the description hedges with 'validation errors OR constraints,' which leaves the actual return semantics ambiguous. It also does not distinguish itself from closely-named siblings like get_form_settings or get_form_definition, so an agent cannot confidently pick it over them from the text alone.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_form_settings or update_form_settings, despite four sibling tools operating on the same 'form settings' resource. The agent is left to infer when this tool applies versus its neighbors.

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

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

With no annotations, the description carries the full burden and largely delivers: it discloses silent overwrite of existing files, mode preservation, 0600 for new files, streaming (never inlined), and that temp files persist after return. It stops short of error behavior (e.g., missing image) and authentication requirements, keeping it out of the top band.

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 organized into short paragraphs covering disk behavior, temp-file default, and content-type reporting. Every sentence is informative, though the closing note about the response media type and the restated tilde-expansion edge toward redundancy with the schema/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 two-parameter read/download tool with a high-coverage schema and an existing output schema, the description covers everything an agent needs: where the file lands, what happens to existing files, permissions, and the lifecycle of temp files. Return-value explanation is optional here and its presence is harmless.

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, and the description genuinely exceeds it by explaining the overwrite/mode semantics tied to output_path and restating that temp files persist for the caller to use or delete. The tilde-expansion and relative-path resolution it restates are already in the schema, so it is additive rather than purely new.

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 opening sentence gives a specific verb and resource ('Download an image to a file, written to disk') and immediately clarifies the streaming-to-disk model. No sibling tool in the list downloads images (upload_image is the inverse), so the agent can identify the correct tool without ambiguity.

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

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

There is no explicit guidance on when to choose get_image versus alternatives, and no exclusions or prerequisites. Usage is only implied by the detailed discussion of the omitted-output_path path and temp-file workflow, which tells the agent how it will behave rather than when to reach for 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 declare readOnlyHint=true, so the safety profile is already covered. The description adds real behavioral context the annotations cannot: output is streamed as newline-delimited JSON and capped at max_rows specifically to bound context size. It stops short of describing truncation/pagination interplay, but that lives in the max_rows schema description.

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

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

Front-loaded with the core action and stream format, then the differentiation. Slightly redundant: the 'postponed submission metadata only' point is made twice (paragraph two and the closing sentence), which is the only wasted space.

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?

Output schema and annotations exist, so return structure need not be explained. For a streaming, capped read tool the description supplies stream format, cap purpose and sibling routing — enough to call it correctly. Only the truncation/increment interaction is left implicit.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including max_rows default, truncation behavior and the increment cursor. The description only restates the max_rows cap, adding no syntax or format detail beyond the schema. 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 ('stream postponed submission metadata for a form') and immediately names the sibling it must not be confused with. The distinction from get_submission_metadata is spelled out, so an agent can differentiate 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?

Explicitly routes the agent: use this for postponed submissions only, get_submission_metadata for all submission metadata. That covers the primary selection decision, but there is no guidance on when postponed-only retrieval is preferable (e.g. follow-up workflows) or on the incremental-pagination parameter beyond what the schema says.

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 readOnlyHint annotation, the description discloses real behavioral traits: the response is JSON wrapping the syntax, it carries a size signal and a truncation flag, and output is capped at max_chars. The caller is told to check 'truncated' to detect a cut response, which is genuinely useful operational 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?

The core capability and the truncation caveat are front-loaded and the passage is short. The middle sentence about what 'the spec documents' is slightly meta and redundant with the first sentence, costing a little efficiency.

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 and readOnlyHint declared, the description need not explain return values; it still adds the one thing the schema cannot convey — the truncation risk and how to detect it. Nothing needed 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?

Schema coverage is 100%, so both form_id and max_chars are already documented in the schema, including the default and the newline-boundary truncation rule. The description restates the max_chars cap and truncation behavior without adding syntax or format detail the schema lacks, 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: 'Get SPSS syntax for a form's submission data,' which an agent can distinguish from CSV/Excel export siblings. It does not explicitly name those alternatives, 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?

Usage is implied (retrieve syntax for statistical use on a form's data) but there is no explicit when-to-use, when-not-to-use, or guidance against the nearby export_form_csv / export_form_excel siblings. An agent must infer the choice from the format name 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, so the safe-read profile is covered structurally. The description usefully discloses that the response bundles answers plus metadata, but adds nothing on auth needs, scoping, or missing-submission behavior; with an output schema present, return details are largely covered elsewhere.

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

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

A single efficient sentence with the resource and payload front-loaded and zero filler. It is appropriately sized, though so terse that it forgoes the disambiguation that would earn a 5.

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 read tool, with readOnlyHint annotations and an output schema covering returns, the description supplies enough to invoke it correctly. The one gap is failing to distinguish it from the similarly named get_submission_metadata sibling.

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% with a single well-described submission_id, so the schema carries the parameter semantics. The description adds no format or provenance 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 (Get) and resource (a single submission) and clarifies the payload includes answers and metadata, which separates it from the list_my_submissions sibling. However, it does not differentiate itself from near-name siblings like get_submission_metadata or get_submission_pdf, which the description's mention of 'metadata' actively blurs.

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

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

There is no guidance on when to use this tool versus get_submission_metadata, get_submission_pdf, or get_form_answers, all of which sit in the same sibling set. No prerequisites or context for choosing it 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?

With readOnlyHint=true already covering the safety profile, the description adds real behavior: NDJSON streaming so a large form is never held whole in memory, a max_rows cap, and the truncated flag to detect truncation. It also candidly discloses that the API docs do not specify the include/exclude relationship with postponed submissions — useful for an agent reasoning about overlap.

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 streaming behavior are front-loaded, then usage guidance, then the sibling distinction. Mostly tight, though the closing paragraph on the unspecified postponed relationship is slightly verbose for what it conveys.

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 documented, and the description covers streaming, capping, truncation, and sibling boundaries. It would be fully complete if it linked the truncated stream to continued pagination via submission_ids_greater_than, since that is the natural next step for a bulk exporter.

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 goes beyond it by explaining the semantics of the max_rows cap and the resulting truncated field behavior. It does not, however, explain how submission_ids_greater_than can be used to continue past a truncated stream, leaving that 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 and resource ('Stream all submission metadata for a form, as newline-delimited JSON') and explicitly scopes it to metadata-without-answers. It also names the sibling it differs from (get_postponed_submission_metadata), so an agent can separate the two 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 clear positive contexts ('bulk export of submission-level fields', 'find which submissions exist before fetching their answers') and routes the postponed-metadata case to a named sibling. It stops short of stating exclusions against answer-fetching siblings like get_form_answers, but the 'without answers' framing implies the boundary.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses that the PDF is written to disk rather than returned inline, that existing files are silently overwritten with mode preserved, that new files get mode 0600, and that temp files persist after return. This is exactly the behavioral context an agent needs.

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

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

Front-loaded with the core purpose, then details. Slightly longer than necessary with some restatement of temp-file behavior repeated across the main text and schema, but 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 two-parameter download tool with an output schema handling return values, the description covers the file-system side effects comprehensively. 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%, so the baseline is 3. The description reinforces output_path's temp-file default and tilde expansion but adds little syntactic meaning beyond what the schema already documents.

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 ('Download a submission as a PDF file') that unambiguously distinguishes it from get_submission (JSON) and get_submission_metadata siblings. An agent knows exactly what it produces.

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 purpose implies usage, but there is no explicit when-to-use versus alternatives such as get_submission or get_answer_attachment, and no stated prerequisites or conditions. Adequate but with clear gaps.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description is not carrying the full safety burden. It adds useful context that the record returned is the caller's own ("authenticated API client"), which explains why the tool takes no parameters, but it offers nothing about failure modes or errors.

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 action, with no filler. The "Returns: The user record as JSON" line is mildly redundant given that a full output schema is provided, but it costs little.

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

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

This is a simple, parameterless read tool with an output schema already documenting the return shape, so the description needn't explain fields. What remains is minor: no guidance on auth failure behavior or on how this differs from check_auth_status.

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 there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. The description correctly reinforces that resolution is implicit via the authenticated client.

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 ("Get the Nettskjema user record") and scopes it to the authenticated API client, so an agent knows exactly what comes back. It does not, however, differentiate itself from the nearby sibling check_auth_status, which an agent could plausibly confuse with this 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 statement of when to use this tool versus alternatives. The phrase "for the authenticated API client" implicitly conveys that no user identifier is needed, but no prerequisites, exclusions, or sibling routing 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?

The readOnlyHint annotation already establishes that this is a safe read operation, so the description's burden is to add context beyond that. It adds essentially nothing: it does not define what counts as 'personal data', explain the 'inactive_personal_data_suspected' heuristic, or mention result volume/pagination, and instead largely restates the tool name.

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

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

A single short sentence, front-loaded with the verb and scope, with no wasted words. It is efficient, though its brevity reflects under-specification rather than tight editing.

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 and 100% parameter coverage, the definition is minimally complete for calling the tool. However, it never defines the domain concept ('personal data') that drives the whole listing, nor distinguishes the result set from sibling listing tools, leaving a meaningful gap.

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 boolean filters are already fully documented in the schema, including the None-means-all semantics. The description's 'optional filters' is consistent but adds no syntax or meaning beyond the schema, matching the baseline 3.

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 clear verb+resource ('List forms') and narrows it to a specific subset ('that collect personal data'), which separates it from the generic list_my_forms sibling. It stops short of explicitly naming the alternative tool, so it is clear but not fully differentiated.

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?

Beyond the phrase 'with optional filters' there is no when-to-use guidance, no exclusions, and no pointer to the sibling tools (list_my_forms, lookup_form_by_title) that also enumerate forms. An agent must infer the selection criteria entirely.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds a return-shape summary, but since an output schema exists this is largely redundant and it discloses nothing about pagination, ordering, or result limits for what could be a large listing.

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 first sentence is tight and front-loaded, but the 'Returns:' block enumerates fields (formId, title, open, modifiedDate, etc.) that the output schema already documents, adding bulk that does not earn its place against structured data.

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-only list tool with an output schema, the definition covers what an agent needs to call it correctly. Sufficient, though a note on result size or pagination would fully close the loop.

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 there is nothing for the description to disambiguate. Baseline 4 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 (List) plus resource (forms) and a distinguishing scope ('owned by the authenticated API client'), which separates it from siblings like list_forms_collecting_personal_data and lookup_form_by_title. Clear, though it never explicitly contrasts itself with those alternatives.

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

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

No when-to-use statement, no prerequisites, and no named alternatives. The ownership scope implies a use case, but the agent gets no explicit guidance on choosing this over lookup_form_by_title or list_forms_collecting_personal_data.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered by structured data. The description adds the scope constraint (only the authenticated client's submissions) but says nothing about result limits, ordering, or pagination for what could be an unbounded list — a meaningful gap for a list operation.

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

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

The first sentence is front-loaded and states the purpose in one line; the Returns block is compact. The Returns block is largely redundant given that an output schema exists, which slightly dilutes the value of the second paragraph, but nothing is padded or meandering.

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 is not obligated to enumerate return fields, and its scope statement ('made by the authenticated API client') covers the key ambiguity. It stops short of 5 because nothing addresses volume, ordering, or truncation behavior for an unfiltered list.

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 per the baseline there is nothing for the description to disambiguate. The description correctly avoids inventing filter semantics, and the absence of any filter parameters is consistent with the 'list all' phrasing.

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+resource (list submissions) and scopes it to the authenticated API client, which is genuinely clarifying. However, it never contrasts itself with the near-identical sibling list_my_forms or with the submission-scoped get_submission / delete_submissions tools, so an agent must infer the boundary from names alone.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_submission for a single record or list_my_forms for forms. The only usage signal is the implicit 'my' scope in the name, which the description repeats rather than extends.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds nothing behavioral beyond the lookup verb – no note on what happens on a miss (error vs empty), whether the lookup is exact-match or fuzzy, or what scope it searches.

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 short sentence, front-loaded with the verb and resource, and the clarifying parenthetical is placed immediately after the qualifier. Nothing 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?

An output schema exists, so return values need not be described, and the tool is a simple one-parameter read. What is missing for full completeness is failure behavior and how the lookup relates to the id-based form-retrieval siblings.

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 fully documented in the schema. The description's parenthetical 'URL-safe identifier' merely restates the schema's 'titleShort, as it appears in the form's public URL', adding no new syntax or format detail.

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 (look up) and resource (form) with a scoping qualifier (by its short title). It implicitly separates itself from id-based siblings like get_form_info, but it never names an alternative, so sibling differentiation is left to inference.

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

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

Usage is only implied: an agent can infer it should call this when it has the URL-safe title rather than a numeric id. There is no explicit when-to-use/when-not guidance or pointer to get_form_info or list_my_forms as 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 only declare destructiveHint=true; the description adds real behavioral context beyond that: the operation affects every pending invitation, no subsetting exists, and it honestly flags that coverage of batch-created invitations is an unverified inference. It stops short of describing email delivery semantics, failure behavior, or rate limits, which keeps it from a 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?

The core action and its all-or-nothing scope are front-loaded in the first sentence. The middle paragraph on batch-interface uncertainty and the closing paragraph of frontend URLs are useful for routing but somewhat verbose relative to a one-parameter 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 an output schema present, return values need no explanation, and the description covers scope, irreversibility of scope, and alternatives well. The inference caveat about batch invitations is a nice touch, though delivery/failure details remain undocumented.

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 form_id parameter is fully documented in the schema, so the description adds no syntax or format detail beyond it. Baseline 3 is appropriate when the schema carries the parameter 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?

States a specific verb and resource ('Send reminder emails to every pending invitation on a form') and immediately qualifies the scope as all-or-nothing with no subset endpoint. An agent can distinguish this from other invitation-related operations without 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?

Explains the operation is all-or-nothing and explicitly notes that create/view/delete invitations are not available via this MCP server, routing the agent to the web frontend with concrete URLs. It lacks explicit 'when not to call this' conditions versus siblings, but the scope constraints give clear usage context.

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 supply only destructiveHint=true, and the description goes well beyond that: concurrent edits made after get_form_elements are silently overwritten, no version field/ETag/conditional header exists to detect it, and each element is validated against the vendored ElementDTO schema with unknown fields passed through. This is exactly the extra behavioral context the annotation does 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?

The critical destructive warning is front-loaded in the first sentence, and each paragraph (destructive semantics, sibling alternatives, concurrency, validation) covers a distinct concern. It is longer than typical, but the length is justified by the danger of a silent mass-delete.

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 explain return values, and it covers everything else an agent needs: full-overwrite semantics, the get/modify/resend workflow, the update_form_element alternative, lost-update concurrency risk, and validation behavior. Nothing material is missing for a 2-param destructive 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% and the schema already explains that elements is the complete ordered list and that existing elementIds should be preserved. The description restates that same semantic (complete content, omitted elements removed) without adding format, ordering, or elementId syntax details 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?

States a precise verb+resource ('Replace the form's ENTIRE element list') and immediately scopes it as a full overwrite, not an append. It explicitly distinguishes itself from the 'add an element' interpretation and from update_form_element, so an agent can pick between siblings without opening their 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 explicit when-to-use routing: call get_form_elements first and send the modified array back, or use update_form_element for the read-modify-write of a single element. It also warns when NOT to use this by describing the destructive consequence of a partial list, with a concrete example (one-element list on a ten-element form deletes nine).

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 destructiveHint=true; the description adds real substance beyond that by stating 'The API overwrites the existing transcription' (what is destroyed), the undefined-effect case, and the error behavior ('passing an unknown code raises BadRequestError naming the allowed values'). It does not mention permissions or whether the operation is reversible, so it falls short of a 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?

Front-loaded with the core action, then the destructive/overwrite caveat, then parameter semantics. Four sentences, all carrying weight; slightly verbose in the model enumeration but each clause is informative 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?

With an output schema present, return values needn't be described, and the description covers preconditions, overwrite behavior, model set, and flag semantics. Coverage is strong; only auth/permission prerequisites are absent, which is a minor gap for a destructive operation.

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 exceeds it by enumerating the six allowed model values (the schema has no enum) and explaining that language accepts 100+ codes with an error on unknown values. It adds genuine meaning over the schema for model and language.

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+resource: 'Retranscribe an existing attachment with new transcription options.' This clearly distinguishes it from siblings like get_attachment_transcription (read) and upload_submission_attachment (create), so an agent can route correctly 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?

It gives a concrete precondition: the attachment 'must be audio or video; retranscribing a non-media file or a file that was never transcribed has undefined effect.' That is clear when-to-use context. It stops short of naming an alternative tool or an explicit when-not (e.g., 'to read the current transcription, use get_attachment_transcription').

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

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

With no annotations, the description carries the full burden and does so well: it discloses that submission creates a real collected-data row visible to the form owner, that there is no draft or preview, that answers are validated against ClientAnswerDTO before sending, and that unknown fields are passed through to the API.

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 purpose is front-loaded, followed by side effects, the alternative tool, and validation behavior. Every sentence adds useful information, with no redundant restatement of the tool name or 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 mutation tool with an output schema and full schema coverage, the description supplies the essential missing context: real side effects, no preview mode, alternative invocation path, and preflight validation behavior. Nothing critical for correct selection or invocation is 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 schema already documents form_id, answers, and metadata thoroughly. The description adds some behavioral context about validation and pass-through, but it does not materially expand parameter meaning beyond the schema 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: deliver a response to a form as the authenticated API client. It also names the sibling tool to use for invitation-based submissions, so an agent can distinguish it from submit_form_for_invitation.

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 to use submit_form_for_invitation instead when answering on behalf of a specific invitation. It also clarifies there is no draft or preview mode, which gives clear usage context.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses that this is a real, non-draft submission with no preview, that answers are validated against the vendored ClientAnswerDTO schema before the request, and that undeclared fields are forwarded for the API to decide. It does not cover auth requirements, idempotency, or failure/retry behavior, keeping it at a solid 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?

Front-loads the purpose and sibling contrast in the first two lines, then layers behavioral caveats. Slightly verbose in the second paragraph and the validation sentence, but every sentence carries information 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?

An output schema exists, so return values need not be explained, and the description covers the mutation semantics, validation behavior, and the id-vs-form-id distinction. Given no annotations, it comes close to complete, with only auth and error-handling context missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including that invitation_id is not a form ID. The description reinforces this distinction but adds little syntax or format detail beyond the schema, landing on the baseline 3.

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 ('Deliver a response to the form a given invitation was issued for') and immediately distinguishes itself from the sibling submit_form by addressing mechanism ('addressed by invitation rather than by form'). An agent can route between submit_form and submit_form_for_invitation 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?

Explicitly contrasts with the submit_form alternative and clarifies the key selection condition (invitation's numeric id, not the form's), plus rules out draft/preview use. It stops short of naming a 'when not to use' condition beyond the submit_form contrast, so a 4 rather than 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?

With only destructiveHint=true available, the description carries the rest: it discloses that the operation is NOT atomic, that concurrent edits are silently overwritten, that no version/ETag/conditional header exists to detect conflicts, and that `changes` merges only one level deep (whole answerOptions/subElements/validationScripts lists are replaced). This is exactly the beyond-annotations context an agent needs.

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

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

The key scoping insight is front-loaded in the first sentence, and the remaining paragraphs each carry a distinct, non-redundant warning (atomicity, merge depth, no-op behavior). It is long, but nearly every sentence earns its place; density is the trade-off for a genuinely subtle 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?

For a mutation tool with an output schema, all the dangerous, non-obvious behavior — read-modify-write mechanics, race conditions, shallow merge, list-replacement, and no-op cases — is covered. Nothing an agent needs to invoke it safely 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 baseline is 3, and the description goes further by explaining the shallow one-level merge semantics, the empty-changes prohibition, and why elementId must not appear in `changes`. Field-type validation against the vendored ElementDTO is mentioned too, adding meaning beyond the raw 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 ('Change one element') and immediately explains the non-obvious mechanism (rewriting the form's entire element list). It distinguishes itself from replace_form_elements (same whole-list PUT) and get_form_elements (the read prerequisite), so an agent can tell the three apart 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 explicit prerequisites ('Fetch the element with get_form_elements first'), names the sibling that shares the write path (replace_form_elements), and states the failure/no-op conditions (unknown elementId → nothing written; empty or elementId-bearing changes rejected). When-to-use versus the alternative is clear.

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

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

With no annotations to lean on, the description carries the full burden and delivers: partial-apply semantics, a 207 Multi-Status partial-failure mode surfaced as an error, local partial-DTO validation with relaxed required fields, and local rejection of unknown keys. These are non-obvious runtime behaviors an agent could not infer from the schema.

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

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

Front-loaded with the core action in sentence one, then layered detail on partial updates and validation. Every sentence adds something, though the block is longer than strictly needed for a 3-parameter 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?

For a mutation tool with no annotations and a nested settings object, the description covers the mutation scope, partial-failure reporting, and client-side validation behavior. Return values are covered by the output schema, so nothing essential is missing.

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

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

Schema coverage is 100%, so 3 is the baseline, but the description adds real meaning for the `settings` dict: it is validated as a partial FormSettingsDTO, required constraints are relaxed, and unknown keys are rejected locally. That is more than the schema's one-line 'dict of settings' note, though `force_cleanup` is left unexplained.

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 (update) and resource (settings on an existing form), with a clear scope ('one or more settings'). It does not explicitly name the sibling it differs from (e.g., get_form_settings or get_form_settings_validation), but the verb makes the intent unambiguous.

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

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

Explains the partial-update contract (only keys present are changed) and the 207 Multi-Status outcome, which is exactly the context an agent needs before choosing this over a replace/put-style sibling. It stops short of naming explicit alternatives or when-not-to-use conditions.

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

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

Annotations only declare destructiveHint=true; the description goes further by disclosing the destructive mechanism (omitted entries may delete mappings) and clarifying the spec's silence on preservation. This is exactly the extra 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?

Front-loaded with the purpose, then the risk, then the mechanical guidance. Slightly repetitive in restating the omission risk twice, but every paragraph carries actionable content.

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

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

A destructive mutation with an output schema and full annotation coverage; the description supplies the missing risk semantics. Nothing critical is absent, though it could note the effect on the form definition itself.

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 real meaning: all three maps are required by CodebookDTO and empty dicts are the correct way to express 'no mapping'. That is operational guidance beyond the schema's type declarations.

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: 'Upload a codebook mapping form elements to external identifiers.' It is clearly distinct from siblings like update_form_element or replace_form_elements, though it does not name a sibling to contrast against.

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 tells the agent to send the complete mapping and to send an empty dict for maps not needed, and warns that omitting entries has undefined effect. This is precisely the when/how-to-use guidance needed for a replace-style upload.

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

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

With no annotations, the description carries the full behavioral burden and does substantial work: it discloses in-memory file reading, base64 encoding, JSON string body format, derived filename query parameter, and uncertainty about the server's actual expected body. It omits auth, error handling, and size limits, but is unusually transparent for a no-annotation tool.

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 purpose is front-loaded, but the description is bloated with speculative OpenAPI and Spring Boot implementation details. The final paragraph about an uncertain serialization artefact is lengthy and may confuse an agent more than it helps; a shorter description would be more effective.

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 explained, and the description covers the upload's unusual body handling and the one required input. It still lacks auth requirements and error behavior, but is largely complete for a one-parameter upload tool with no annotations.

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% for the single file_path parameter, so the schema already documents its meaning and acceptable forms. The description adds behavioral context about filename derivation but does not deepen the semantics of file_path itself, so the baseline of 3 is appropriate.

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

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

The first sentence states a clear verb and resource: 'Upload an image to the API.' It is specific enough for an agent to understand the operation, but it does not distinguish this tool from sibling upload tools such as upload_submission_attachment or upload_codebook.

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

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

The description gives no explicit guidance about when to use this tool versus alternatives. It implies usage for image uploads but never names conditions, exclusions, or sibling tools, leaving the agent to infer 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?

With destructiveHint=true already declared, the description still adds substantial context: the whole file is read into RAM, filename/fileSize are derived rather than passed, the attachment token authorizes writes to someone else's submission and must be secured like an access token, and an upload may silently replace an existing attachment. The silent-replacement warning corroborates the destructive hint rather than contradicting it.

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 purpose is front-loaded and most sentences carry distinct, useful information. It is somewhat long and repeats the in-memory file handling across two sentences, but nothing is filler and the structure remains readable.

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 mutation tool with four required parameters and a security-sensitive token, the description covers authorization requirements, side effects, memory behavior, and transcription applicability. With an output schema present and annotations covering the destructive flag, nothing an agent needs to call this safely 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 baseline is 3, but the description adds real meaning beyond the schema: it enumerates the six supported transcription models, states that unknown language codes raise BadRequestError naming allowed values, and explains that diarize and translate_to_english only apply after transcription. The model enum values in particular are absent from the schema and materially help invocation.

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 states a specific verb (upload) and resource (an attachment to a submission question) plus the optional transcription facet. This cleanly separates it from siblings like upload_image and upload_codebook, which target different resources. An agent can identify the operation 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 gives conditional context (transcription options apply only to audio/video, and the token must originate from the submission-creation response), which implies when the tool is applicable. However, it never routes the agent against the obvious alternatives such as upload_image or retranscribe_attachment, so usage guidance remains implicit rather than explicit.

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