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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds useful behavioral context beyond annotations: activation occurs after consistency checks, explicit confirmation is required, the underlying RemoteControl method is named, and session-key authentication is explicitly excluded.

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

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

The description is two tight paragraphs. The first front-loads the purpose and the required confirmation; the second adds implementation and authentication details. Every sentence contributes directly to correct invocation without padding.

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

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

For a non-idempotent mutation tool with 4 parameters, an output schema, and annotations covering safety, the description covers purpose, required confirmation, consistency-check sequencing, authentication constraints, and the RemoteControl method. It could say more about failure modes if consistency checks fail, but it is largely complete given the structured data.

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 survey_id, confirm_activation, response_format, and activation_settings in detail. The description repeats the confirm_activation=true requirement but adds no syntax, format, or default information beyond the schema, 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?

The description states a specific verb and resource: 'Activate a survey'. It also adds the precondition 'after LimeSurvey consistency checks'. However, it does not distinguish this tool from the sibling limesurvey_activate_tokens beyond the resource name, so sibling differentiation is absent.

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 provides an implied usage context ('after LimeSurvey consistency checks') and notes the required confirm_activation=true acknowledgement. It does not state when not to use this tool or name alternatives such as limesurvey_activate_tokens or limesurvey_add_survey, leaving routing to inference.

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

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

The description usefully adds auth context beyond annotations ('uses the configured service account; do not provide a session key') and names the underlying RemoteControl method. However, with idempotentHint=false it does not explain what happens on repeated activation, nor does it disclose side effects such as replacing/locking participant data — meaningful gaps for a table-creating mutation.

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

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

Two short sentences, the action front-loaded and the auth constraint placed second. No filler; every sentence carries actionable information.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. Still, for a mutation that creates the participant table, the description omits prerequisites and the consequence of re-running, leaving the definition only minimally complete.

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

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

Schema description coverage is 100%, so the schema already documents survey_id, response_format, and attribute_fields. The description's mention of 'optional custom attributes' loosely maps to attribute_fields but adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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

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

States a specific verb and resource: 'Create the survey participant table and optional custom attributes.' An agent can distinguish this from sibling operations like get_participant_table_status or add_participants, though it never explicitly contrasts with them.

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 by the purpose ('create the table'). There is no explicit when-to-use guidance, no mention of preconditions (e.g. that the survey must exist or that the table must not already be active), and no reference to the related sibling limesurvey_get_participant_table_status that would help an agent decide.

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 the write behavior (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description adds genuinely useful non-obvious context about authentication (service account, no session key), but says nothing about side effects such as duplicate titles or what happens to an existing survey structure. With annotations carrying the safety profile, this is a modest but real addition.

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 and only two short sentences total. The RemoteControl method reference is marginal but compact; nothing is bloated.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. However, for a 4-parameter mutation tool with many create-group siblings, the description omits any differentiation from import_group/add_group_from_spec and any note on duplicate handling or ordering, leaving meaningful gaps.

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 every parameter (survey_id, title, description, response_format) is already documented in the schema with types and constraints. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('Add an empty question group to a survey'), and the 'empty' qualifier meaningfully scopes the operation. It is clearly distinct from delete/import/set siblings by implication, though it never names an alternative to differentiate against 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?

Usage is only implied: 'empty' suggests this is for creating a fresh group to be populated later, in contrast to import_group or add_group_from_spec, but no when-to-use, when-not-to-use, or alternative is stated. An agent must infer the routing from the tool 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?

With annotations only covering the safety profile, the description carries rich behavioral context: pre-import validation (languages, free question codes, case-insensitive) with named failures that write nothing, exactly what gets moved (only the new group), a read-back verification step, rollback behavior when a later step fails and the distinct no-delete path when the import outcome is unknown. That is far beyond what the annotations declare.

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 action and its constraints are front-loaded in the first sentence, and given the tool's failure modes most sentences earn their place. It is, however, a single dense paragraph with no visual separation between mechanics, errors, and return shape, which makes it harder to scan than its content warrants.

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 destructive-capable spec import with nested objects, this is essentially complete: preconditions, validation and error codes, rollback semantics, unknown-outcome handling, scope requirement, and an unusual Ranking-question quirk. The return shape is also described even though an output schema exists, so nothing an agent needs 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 the schema cannot: it identifies the group spec as the exact format limesurvey_get_survey_spec emits at level group, explains the one-string-or-language-map convention for every text, and clarifies that position without a value defaults to the end. These are cross-tool format contracts, not restatements.

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

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

Opens with a specific verb and resource: 'Insert one new group with its questions into an inactive survey, described as a group spec.' It scopes the operation (one group, its questions, inactive survey only) and explicitly names the sibling boundary ('A single question goes with limesurvey_add_question_from_spec'), so an agent can distinguish it from add_question_from_spec and create_survey_from_spec 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 clear preconditions and routing: an active survey is refused, the spec must come from limesurvey_get_survey_spec at level group, and single questions belong to the sibling tool. It also states the required write scope. It does not, however, contrast itself with the non-spec sibling limesurvey_add_group, which is the most obvious alternative for adding a group.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description adds a genuinely useful operational detail — authentication uses the configured service account and no session key should be supplied — but says nothing about what happens when the language already exists, which matters given idempotentHint=false.

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

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

Two short sentences, the action front-loaded, and each clause carries distinct information (purpose, underlying RemoteControl method, auth expectation). No filler or restatement of the title.

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 annotations covering the mutation/safety profile, the description need not explain return values, and it supplies the auth detail that would otherwise be missing. The one gap is duplicate-language behavior, which the agent cannot derive from annotations or schema given idempotentHint=false.

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 survey_id, language, and response_format are already documented in the schema; the description adds no format hints or constraints (e.g., which ISO codes are accepted). This is the baseline case where the schema does the heavy lifting.

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

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

States a specific verb and resource ('Add a language to a survey'), which is unambiguous about the action taken. It does not, however, distinguish itself from nearby siblings such as limesurvey_delete_language, limesurvey_set_language_properties, or limesurvey_get_survey_languages, so the agent must infer the boundary 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?

The description says what the tool does but gives no when-to-use, when-not-to-use, or alternative routing. It never mentions that get_survey_languages is the read counterpart or that set_language_properties handles modifications to an existing language, which is exactly the ambiguity an agent faces in this large sibling set.

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 (readOnlyHint=false, destructiveHint=false) indicate mutation but non-destructive behavior. The description adds no further behavioral context such as what happens if a participant already exists, validation rules, or side effects. Minimal transparency beyond structured data.

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?

Single sentence, front-loaded with verb and resource. Concise, but could be slightly more informative without losing brevity. No fluff.

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 3 parameters, nested objects, and an output schema, the description is too brief. It doesn't mention return values, required session key, or that the survey must exist. Incomplete for effective tool invocation.

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

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

Schema description coverage is 67%, so baseline is 3. The description 'simple participant object' hints at the nature of the participant parameter but adds little beyond the schema's own description. No extra meaning for survey_id or create_token.

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 'Add one participant using a simple participant object' clearly states the action and differentiates from the sibling limesurvey_add_participants (plural) by specifying 'one'. However, it does not explicitly mention that the participant is added to a survey, though the survey_id parameter implies it. Slightly vague but sufficient.

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 guidance on when to use this versus alternatives like limesurvey_add_participants for batch adds. No prerequisites, no mention of token creation default or when to set create_token to false. Lacks contextual usage advice.

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

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

Annotations already declare readOnly=false, idempotent=false, destructive=false and openWorld=true, so the safety profile is covered. The description usefully adds auth behavior ('uses the configured service account; do not provide a session key') and names the underlying RemoteControl method, which prevents a common invocation error.

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 with no filler; the purpose leads and the auth constraint follows. Every clause carries information.

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

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

An output schema exists so return values need not be explained, and parameters are documented. But the participants array is loosely typed (anyOf over all types) with only 'Participant records.', and the description does not compensate by indicating the expected record shape, which is the main thing an agent could get wrong.

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

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

Schema description coverage is 100%, so all four parameters are already documented structurally. The description adds nothing about survey_id, create_token, participants, or response_format, so the baseline of 3 applies.

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

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

States a clear verb+resource (add participants to a survey) and the plural 'one or more' hints at a bulk operation. However, it never distinguishes itself from the closely-named singular sibling limesurvey_add_participant, nor from limesurvey_cpd_importParticipants, so an agent could still pick the wrong add variant.

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, when-not-to-use, or alternative routing is given. With siblings like add_participant, invite_participants, and cpd_importParticipants, the description provides no guidance on which add path applies to which situation.

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

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

Goes far beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false): it enumerates validation codes that write nothing (SPEC_INVALID, CODE_CONFLICT, SURVEY_ACTIVE, etc.), the import_question side effect on translation gaps that 'cannot be undone', the rollback behavior on post-import failure (delete-and-report), and the unknown-outcome path where nothing is deleted. It also names the required write scope, which the annotations do not convey.

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

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

Purpose is front-loaded, but the remainder is a dense, comma-chained wall of edge cases and error codes with little structural separation. Every clause is informative, yet the run-on delivery makes it hard for an agent to parse; bullets or grouping of the failure paths would help.

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

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

For a complex mutation tool with nested spec objects, validation, rollback, and irreversible side effects, the description is thorough. Return-shape detail is somewhat redundant given the output schema exists, but completeness for correct invocation is not in question.

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 parameters. The description nonetheless adds meaning the schema lacks: the code must be free across the whole survey case-insensitively, the spec is one string or a per-language map, and the acknowledge/fill_translation_gaps semantics. This is above the baseline but position formatting largely repeats 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?

Opens with a precise verb+resource+constraint: 'Insert one new question into a group of an inactive survey, described as a question spec.' It also distinguishes itself from the relevant sibling by noting 'A whole group goes with limesurvey_add_group_from_spec,' so an agent can separate this from add_group_from_spec and update_question_from_spec.

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 preconditions and routing: 'an inactive survey' is required, 'An active survey is refused,' the spec must come from limesurvey_get_survey_spec at level question, and whole-group insertion is redirected to limesurvey_add_group_from_spec. The acknowledge flag is also tied to a specific risky condition, making the when-to-use conditions 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?

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the mutation profile is covered. The description adds genuinely useful context the annotations do not: authentication uses the configured service account and no session key should be supplied. It stops short of describing persistence or side effects on existing surveys.

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 with the action front-loaded and the auth note clearly separated. No filler, though the second sentence could be slightly tighter.

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 auth prerequisite is covered. For a 10-parameter mutation tool, however, the absence of any when-to-use routing relative to the other quota tools leaves 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 all 10 parameters are already documented in the schema. The phrase 'with minimum details' hints that only the 3 required fields are needed, but adds little semantic detail beyond what the schema provides. 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 ('Create a quota') and even names the underlying RemoteControl method, so an agent knows exactly what it does. It does not explicitly differentiate from siblings like set_quota_properties or list_quotas, but the create-vs-modify distinction is inferable from the verb.

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 says only 'with minimum details' and gives no guidance on when to use this versus set_quota_properties, get_quota_properties, or list_quotas. There are no exclusions or alternative routing, leaving usage 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 readOnly=false, idempotent=false, destructive=false, openWorld=true, so the safety profile is covered. The description adds genuinely new operational context: the underlying RemoteControl method name and the fact that authentication is handled by a configured service account so no session key is passed. It stops short of saying what happens to duplicate submissions or how failures surface.

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 with the action front-loaded and no filler; the auth caveat is placed last where it belongs. It is efficient, though the RemoteControl method-name sentence is only marginally useful to an agent making a selection call.

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 not be described, and the 100%-covered schema handles the parameters. The one thing an agent could easily get wrong in this tool family – passing a session key – is explicitly addressed, so the definition is nearly complete for a 3-param write 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% (survey_id, response, response_format are all documented in the schema, including the json/markdown trade-off), so the baseline of 3 applies. The description adds no syntax, format, or field-mapping detail beyond what the schema already states.

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 ('Insert a response into a survey response table'), which pairs with the title 'Add survey response' to make the operation unambiguous. It does not, however, distinguish itself from the adjacent limesurvey_update_response or limesurvey_delete_response siblings, which share the same resource.

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 by the verb 'insert' – there is no explicit when-to-use vs. update_response/delete_response guidance or stated prerequisites (e.g. survey must be active, tokens required). The auth note ('do not provide a session key') is a partial guideline, but it is framed as a usage constraint rather than a scenario selector.

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

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

Annotations already cover the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds genuinely useful behavioral context: auth is via the configured service account and no session key should be supplied. The only weakness is the somewhat filler note about the underlying RemoteControl method 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?

Two short, front-loaded sentences with the core purpose first and an operational note second. Little waste, though the RemoteControl method-name detail is marginally low-value.

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. The description covers purpose and the authentication prerequisite, which is what an agent needs to call it correctly; it could say a bit more about what 'minimum settings' defaults to, but nothing critical is missing.

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

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

Schema description coverage is 100%, so all five parameters (including the survey_id=0 convention and response_format enum) are fully documented in the schema. The description adds no parameter-level meaning, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Create an empty survey with minimum settings'), and the 'empty'/'minimum settings' qualifier subtly separates it from import_survey, copy_survey, and create_survey_from_spec. It does not name those siblings explicitly, so differentiation is left partly 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 implied by 'empty survey with minimum settings' but there is no explicit when-to-use or when-not-to guidance. With several survey-creation siblings (import, copy, from_spec), the description never routes the agent between them.

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 annotations only declaring the safety profile, the description carries the real behavioral burden and delivers: it discloses the LimeSurvey quirk that the API answers {"template": true} even when it keeps another theme, and defines three distinct failure modes (THEME_NOT_APPLIED, THEME_NOT_VERIFIED with written: true, THEME_PREVIOUS_UNKNOWN with written: false). This is exactly the kind of non-obvious behavior annotations cannot express.

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

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

Purpose and workflow are front-loaded, then error semantics, then the exclusion note. Every sentence is load-bearing given the error codes, but the error paragraph is dense and could be grouped more readably. Appropriately sized for the complexity.

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 critical read-back semantics and error taxonomy an agent needs to interpret results. Combined with the mechanism steps and the inherit exclusion, nothing required to call and interpret this tool 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 67%, so the schema documents theme_name and confirm_theme_assignment but not survey_id. The description adds real value for theme_name by cross-referencing its source ('installed_theme_name of limesurvey_generate_survey_theme') and the name pattern example. It leaves confirm_theme_assignment and survey_id to the schema, so it adds meaning but not full 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 description opens with a specific verb+resource ('Assign an already imported LimeSurvey survey theme') and spells out the actual mechanism (read previous_theme, set via set_survey_properties, read back). It distinguishes itself from siblings by explicitly excluding theme upload/install and routing the 'inherit' case to limesurvey_set_survey_properties. An agent can tell this apart from generate/validate theme or generic set_survey_properties 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 concrete when/when-not guidance: 'inherit is refused; set it with limesurvey_set_survey_properties or in the admin interface' and 'This does not upload or install the theme package.' These exclusions route the agent correctly. It stops short of a full decision map to other theme siblings (e.g. list_installed_themes as a prerequisite), so not quite a 5.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description still adds value annotations do not carry: it names the underlying LimeSurvey RemoteControl method `copy_survey` and states the authentication model (service account, no session key supplied by the caller). It does not say what else is duplicated (groups, questions, settings) or that repeated calls create additional copies.

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 with the core action front-loaded and zero filler. The authentication caveat is the only addition and it earns its place by preventing an incorrect session-key argument.

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; the schema documents the parameters, and the annotations carry the safety semantics. What remains—purpose, invocation mechanics, auth model—is covered, making this complete for a simple copy 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 description coverage is 100%, so all four parameters (including the optional `destination_survey_id` and the enum-backed `response_format`) are documented in the schema itself, making 3 the baseline. The description only echoes the `new_name` concept and adds no syntax, constraints, or meaning 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?

The description states a specific verb and resource ("Copy an existing survey") plus the resulting scope ("under a new name"), so the action is unambiguous. It does not, however, explicitly differentiate itself from nearby siblings like limesurvey_add_survey, limesurvey_import_survey, or limesurvey_create_survey_from_spec, which an agent might also reach for when duplicating survey content.

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 and no named alternatives; the only explicit guidance is operational ("Authentication uses the configured service account; do not provide a session key"). The use case (duplicating an existing survey) is implied by the verb but not contrasted with import/create alternatives, so the agent must 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?

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true), so the bar is lower. The description adds genuinely useful operational context the annotations do not: authentication uses the configured service account and the caller must not supply a session key. It still does not explain dedupe/matching behavior or interaction with update_existing.

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; the purpose is front-loaded and the auth constraint follows immediately. Nothing is wasted and there is no boilerplate.

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 full parameter documentation, the description covers purpose and the non-obvious auth model. It leaves minor gaps: what key is used to match existing records, and what happens on duplicate/partial imports when update_existing is false.

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 (participants, response_format, update_existing) are already documented in the schema. The description adds no format, matching, or syntax detail beyond what the schema provides, which is 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: 'Import records into the central participant database', which distinguishes the central participant database from survey-level token tables. It does not explicitly name the nearest sibling (limesurvey_add_participants) or state how this differs from it, so it stops 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?

Usage is implied by 'central participant database' but the description never says when to choose this over limesurvey_add_participants, limesurvey_add_participant, or limesurvey_validate_participants, and gives no prerequisites. No explicit when/when-not guidance is present.

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

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

Far beyond what the annotations declare, the description discloses the full behavioral contract: the spec is validated before anything is sent, the created survey 'stays inactive and is not activated,' the tool reads the survey back with read methods only, and it details error codes (SPEC_INVALID, CREATE_SURVEY_FAILED), details.created=false/'unknown' with manual_cleanup and a named recovery path, plus response truncation rules (200 entries, LIMESURVEY_MAX_RESPONSE_CHARS) and the write-scope requirement. Annotations only cover the safety profile, which matches (non-destructive, not idempotent, no contradiction).

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

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

It is front-loaded with the core purpose, but the body is an extremely dense, run-on paragraph mixing validation, error codes, return shape, truncation, and version-specific quirks with little formatting. Much of it earns its place, yet the lack of structure makes it hard to scan.

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 high-complexity, nested-spec creation tool, the description covers success, validation failure, import failure, partial failure, truncation, and version-specific edge cases. It even restates the return shape (redundant given the output schema) but nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% (baseline 3), and the description adds real semantics beyond it: language handling ('one string for every language or a map per language'), the scale_id convention for the second scale of types 1, : and ;, and the Ranking-question read-back behavior that differs across LimeSurvey 6 and 7. This clarifies cross-field relationships the flat schema cannot.

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+resource ('Create a new survey from a survey description') and immediately scopes it with '(spec { survey, groups })'. It actively distinguishes itself from siblings: import_survey consumes the generated .lss, validate_spec pre-checks, get_survey_spec reads an existing spec, and it explicitly states it 'takes no file path, adds nothing to existing surveys, activates nothing and deletes nothing.' An agent can place this among add/import/activate without opening another 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?

Clear context is given: use this when you have a spec, check it first with limesurvey_validate_spec, and use limesurvey_get_survey_spec to obtain a spec for an existing survey. The negative scoping ('adds nothing to existing surveys, activates nothing, deletes nothing') further routes the agent away from sibling mutation tools. It stops short of an explicit when-not-to-use statement for add_survey vs this tool, so it is strong but not exhaustive.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: it names the underlying RemoteControl method and clarifies that auth uses the configured service account with no session key supplied, which is non-obvious given the sibling session-key tools. It omits whether contained questions are cascaded/removed with the group, the one notable behavioral gap.

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

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

Two sentences plus a short auth note, with the action and precondition front-loaded and zero filler. Every sentence carries information the agent cannot get elsewhere.

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 annotations plus the auth/method notes cover the operational essentials. The gap is that a destructive group deletion does not mention the fate of questions inside the group, which an agent might reasonably need before confirming.

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 survey_id, group_id, response_format, and the confirm flag are all documented in the schema itself. The description only restates the confirm flag requirement, adding no syntax or constraint detail beyond what the structured fields provide; 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 (delete a question group from a survey), which cleanly distinguishes it from siblings like limesurvey_delete_survey, limesurvey_delete_question, and limesurvey_set_group_properties. 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 states the precondition that confirm_destructive_action=true is required, which is useful gating context. However, it gives no guidance on when to choose this over alternatives (e.g., set_group_properties to modify rather than remove) and no exclusions or consequences of proceeding.

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

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

Annotations already flag destructiveHint=true and non-idempotency, but the description adds real value beyond them: the mandatory destructive-acknowledgement flag and the authentication model ('configured service account; do not provide a session key'). It could go further by stating that removal is irreversible and what happens to translations tied to that language.

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 purpose and the blocking prerequisite, with no redundant restatement of the tool name. Every sentence earns its place.

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

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

For a destructive four-parameter tool with an output schema and rich annotations, the description covers purpose, the safety gate, and the auth expectation. Return values are handled by the output schema, so nothing required 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 survey_id, language, response_format, and confirm_destructive_action are all documented in the schema itself. The description only restates the confirm flag requirement and adds no semantics for the other parameters, matching the baseline for a fully-covered 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 ('Remove a ... language from a survey') and narrows the scope with 'non-base', which separates it from limesurvey_add_language and limesurvey_set_language_properties. An agent can identify the operation 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?

Gives a clear precondition ('Requires confirm_destructive_action=true') and an implicit exclusion via 'non-base language', so the agent knows base languages are out of scope. It stops short of explicitly routing to a sibling (e.g. set_language_properties for edits), so it is not a full when/when-not/alternative statement.

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 idempotentHint=false, so the safety profile is covered. The description adds genuinely new context: the confirmation gate and the authentication model (configured service account, no session key), which the annotations do not convey.

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

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

Two short paragraphs, front-loaded with the action and target, followed by invocation and auth notes. Every sentence carries information an agent needs; nothing is padding.

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

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

An output schema exists, so return values need not be explained. The description covers targeting, confirmation, and auth adequately; it stops short of noting whether deletion cascades to associated responses or how partial failures among multiple token IDs are handled for this irreversible 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 description coverage is 100%, so survey_id, token_ids, and confirm_destructive_action are already documented. The description only restates the token-table row ID meaning, adding no syntax or constraints 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?

State a precise verb+resource and scope: 'Delete participants by token-table row IDs.' This is immediately distinguishable from delete_survey, delete_response, and delete_group, and the ID-based targeting is 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 states the mandatory prerequisite (confirm_destructive_action=true) but gives no guidance on when to choose this over related operations, nor does it mention that token IDs typically come from list_participants. Usage is implied rather than framed.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds useful operational context beyond annotations: it requires explicit confirmation and states that authentication uses the configured service account, with no session key needed.

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

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

The description is short, front-loaded with the destructive action, and every sentence adds operational value. There is no wasted wording or redundant explanation.

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?

Given the rich annotations, full schema coverage, and an output schema, the description is complete enough for correct invocation. It covers the destructive nature, confirmation requirement, and authentication approach, though it could mention irreversible effects more explicitly.

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 question_id, confirm_destructive_action, and response_format. The description mainly repeats the confirmation requirement and adds authentication guidance rather than adding parameter-specific syntax or semantics.

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

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

The description clearly states a specific verb and resource: delete a question from its survey. It is distinct from sibling tools like replace_question or update_question_from_spec, though it does not explicitly name 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?

The description gives a required precondition (confirm_destructive_action=true) but does not explain when to choose deletion over alternatives such as replacing or updating a question. Usage is implied by the tool name and purpose, which is the minimum viable level.

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 openWorldHint=true, so the safety profile is covered structurally. The description adds useful non-annotation context: the confirmation requirement, the backing RemoteControl method, and the authentication expectation that no session key should be provided.

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 required confirmation, followed by implementation and authentication notes. Every sentence earns its place and nothing is padded.

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

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

The definition is complete enough to invoke safely: it identifies the destructive action, requires explicit confirmation, notes authentication expectations, and an output schema exists so return values need not be described. It could add more about downstream effects of deleting a quota, but that is a minor 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 the schema already documents quota_id, response_format, and confirm_destructive_action. The description adds no parameter meaning beyond what is in the schema, 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?

States a specific verb and resource: 'Delete a survey quota.' This clearly distinguishes the tool from sibling quota operations such as list_quotas, add_quota, get_quota_properties, and set_quota_properties.

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 states a required precondition ('Requires confirm_destructive_action=true'), which helps invocation, but it does not explicitly say when to use this tool versus alternatives like set_quota_properties or list_quotas. Usage is implied by the destructive delete verb.

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, readOnly=false, and idempotent=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the deletion is "Permanent," it requires `confirm_destructive_action=true` as a gate, and authentication uses the configured service account so no session key should be supplied. The auth note is real operational value the annotations do not convey.

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

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

Two short sentences, front-loaded with the destructive action and its gate, followed by implementation/auth detail. Every clause earns its place with no filler.

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

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

Return values need not be explained since an output schema exists, and the description covers the destructive nature, the confirmation gate, and authentication behavior. It is nearly complete; only the absence of any failure/error context (e.g., what happens on a missing or already-deleted response) keeps it from 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 all four parameters (including survey_id, response_id, response_format, confirm_destructive_action) are already documented. The description restates the confirm flag requirement, which is already encoded as `const: true` in the schema, adding little beyond the structured data. Baseline 3 is appropriate.

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

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

The opening sentence gives a concrete verb+resource ("Permanently delete a response"), which is unambiguous and matches the tool title. It does not, however, explicitly distinguish itself from the many other delete siblings (delete_survey, delete_participants, delete_group, delete_question), so an agent must rely on the resource noun 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?

The description states the confirmation precondition but gives no when-to-use framing, no alternatives, and no warnings about when deletion is inappropriate (e.g., versus update_response or deactivating a survey). The agent gets a prerequisite, not guidance on when this tool is the right choice.

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, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description still adds useful non-annotation context: the deletion is permanent, and authentication uses a configured service account rather than a caller-supplied session key (relevant given the get_session_key/release_session_key siblings). It stops short of saying what else is destroyed alongside the survey.

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, the destructive nature is front-loaded, and the confirmation precondition and auth note follow in order of importance. Nothing is padded or repeated.

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

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

With an output schema present and annotations covering the safety profile, the description does not need to explain return values, and the auth clarification is a valuable addition. It is slightly incomplete in not warning that deleting a survey also removes its groups, questions, and responses.

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 survey_id, response_format, and confirm_destructive_action are all already documented in the schema. The description only restates the confirmation requirement, adding no syntax or format detail beyond the schema, which makes 3 the correct 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?

The description states a specific verb and resource ('Permanently delete a survey'), and the resource is enough to separate it from the many sibling delete tools (delete_group, delete_question, delete_response, delete_participants, delete_quota). An agent can identify the target of 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?

It gives one concrete precondition ('Requires confirm_destructive_action=true'), which is real usage guidance, but there is no when-to-use vs when-not framing and no mention of alternatives or irreversibility tradeoffs relative to sibling operations.

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 establish the safe read-only, idempotent profile, and the description adds real context on top: the response is base64-encoded (not raw content), it maps to the RemoteControl `export_responses` method, and it authenticates via a configured service account so no session key should be supplied. It omits any note about export size limits, timeouts, or long-running behavior, which is a modest gap.

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

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

Two short sentences with the most differentiating fact — the base64-encoded output — front-loaded. The second sentence is slightly lower value but ties the tool to the upstream RemoteControl method name, which is useful for disambiguation; nothing is padded.

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

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

An output schema exists, so return-value explanation is unnecessary, and 91% schema description coverage carries the parameter burden. The remaining gap is the absence of any export-scoping or size guidance for a tool that can pull an entire response set.

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 91%, so the schema already documents nearly every one of the 11 parameters including the four enums. The description adds nothing about parameter syntax or interactions (e.g. how document_type relates to the base64 payload), so 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 ('Export responses') and pins down the output artifact as 'a base64-encoded document', which implicitly separates it from the limesurvey_export_responses_to_file sibling. It never names that sibling explicitly, so an agent must infer the inline-vs-file distinction rather than being told.

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 or when-not-to-use guidance, and no mention of the by-token or to-file alternatives among the many export siblings. The usage is only implied by the output form (base64 payload returned inline rather than written to a file), which is thin for a fleet of near-duplicate export tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the burden is lower. The description adds real value beyond them: the result is a base64-encoded document, and authentication uses the configured service account with no session key required. It does not, however, note size or rate limits.

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 purpose and followed by the auth constraint. Efficient with no filler, though the second sentence is slightly process-oriented rather than strictly necessary.

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-value explanation is not needed, and the auth note plus encoding note cover the key invocation concerns. Only the relationship to the _to_file and unfiltered siblings 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% and all nine parameters, including enum options, are documented in the schema itself. The description adds no parameter-level meaning, so the baseline of 3 applies.

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

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

States a specific verb (Export), resource (responses), and a scope qualifier (by participant token), plus the output encoding (base64-encoded document). This clearly differentiates it from the unfiltered limesurvey_export_responses, though it does not explicitly name the sibling it differs from.

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 one actionable constraint ('do not provide a session key'), which is useful invocation guidance, but it never states when to choose this over limesurvey_export_responses or the sibling limesurvey_export_responses_by_token_to_file. Usage is implied by the 'by token' scoping rather than explained.

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 indicate readOnlyHint=false (write operation) and destructiveHint=false. The description adds 'securely decode the result inside LIMESURVEY_EXPORT_DIR' but doesn't explain error handling, overwrite behavior, or side effects.

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 18-word sentence is efficient but lacks important details; it is more under-specified than concise.

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?

Despite having an output schema, the description fails to explain the file format, the meaning of 'securely decode', or the effect of many optional parameters (e.g., completion_status, response_type). Incomplete for a tool with 11 parameters.

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

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

Schema coverage is 45%, but the description adds no extra meaning beyond parameter names and schema descriptions. It does not clarify how fields, heading_type, response_type, etc., affect output.

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 uses specific verb 'export' and resource 'responses for selected tokens', clearly distinguishing from siblings like limesurvey_export_responses (no file output) and limesurvey_export_responses_to_file (all responses).

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 explicit guidance on when to use this tool vs alternatives (e.g., limesurvey_export_responses_by_token for in-memory results), nor prerequisites or when-not-to-use scenarios.

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 indicate non-read-only, non-idempotent, non-destructive behavior. The description adds minimal detail: it writes to LIMESURVEY_EXPORT_DIR and decodes base64, but does not disclose file creation, overwrite handling, or permission requirements.

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

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

The description is a single sentence, but it is poorly structured and vague. It includes an oddly specific detail about decoding base64 without explaining why, and fails to convey the core functionality clearly.

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?

Given the tool's complexity (13 parameters, 2 required), the description is severely incomplete. It does not explain return values, output format, or the purpose of key parameters, leaving the agent ill-equipped to use the tool correctly.

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

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

Schema description coverage is low (38%), and the description adds no parameter explanations. Many important parameters like document_type, response_type, and completion_status are left unexplained, forcing reliance on the sparse schema descriptions.

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

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

The description clearly states the tool exports responses, but does not distinguish it from sibling export tools like export_responses or export_responses_by_token_to_file. The mention of decoding base64 inside a specific directory adds specificity but is secondary.

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 guidance on when to use this tool versus alternatives. Sibling tools have similar names and purposes, but the description lacks any comparative context or usage scenarios.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's added value is real: it discloses that the payload comes back base64-encoded rather than as a file, and that auth flows through the configured service account with no session key required.

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

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

Two tight sentences that front-load the purpose and then give the behavioral/auth note. No filler, though it stops just short of the routing detail that would make it maximally useful.

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, and the description still conveys the result encoding (base64 PDF/XLS/HTML). Auth behavior is covered. Only the sibling-routing context 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 description coverage is 100% and the description does not elaborate on any parameter beyond the document types already enumerated in the schema. Per the baseline rule, a 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Export survey statistics') plus the output encodings ('base64-encoded PDF, XLS, or HTML document'). The 'base64-encoded' qualifier implicitly separates it from the sibling 'export_statistics_to_file', but that sibling 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?

Usage is only implied by the tool name; there is no explicit when-to-use statement or exclusion. It does supply one prerequisite ('do not provide a session key'), which nudges it above a bare 2, but the obvious alternative (limesurvey_export_statistics_to_file) is left unaddressed.

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 indicate a write operation with no idempotency and no destruction. The description adds one behavioral detail: 'securely decode the result inside LIMESURVEY_EXPORT_DIR.' However, it does not disclose potential side effects like file overwriting (though the parameters overwrite and confirm_overwrite suggest this). The description adds some context beyond annotations but is still limited.

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

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

The description is a single concise sentence that front-loads the core action. No redundant words. While it is efficient, it sacrifices necessary detail for brevity, which slightly lowers the 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?

Given the tool has 8 parameters, a write operation, an output schema, and annotations, the description is too minimal. It does not explain the output, the meaning of 'securely decode', or how parameters like overwrite interact. The description is not sufficient for an agent to use this tool reliably without additional schema parsing.

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 63%, meaning several parameters (e.g., group_ids) lack descriptions. The tool description does not mention any parameter meaning or usage, thus adding no value beyond the schema. With moderate coverage, the description should compensate but fails to do so.

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 clearly states 'Export survey statistics and securely decode the result inside LIMESURVEY_EXPORT_DIR.' It uses a specific verb (Export) and resource (statistics to file), and the mention of a secured directory distinguishes it from sibling tools like limesurvey_export_statistics which likely returns data directly.

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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, limitations, or contrast with similar tools (e.g., export_statistics for direct output). The agent is left to infer usage 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?

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true), and the description adds real context beyond them: it writes a file to disk rather than returning base64, the internal method fallback order, the exact error code on failure, and the plugin/upstream availability situation. It does not describe overwrite collision behavior beyond the schema's own flags, so a 4 is fair.

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

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

Purpose is correctly front-loaded, but the body is dense with internal sourcing detail (LimeSurvey 6.17.11, handler-class extensibility, PR #5384, a checked-on date) that goes beyond what an agent needs to select and call the tool. Much of it is informative for a human maintainer but inflates the definition for selection purposes.

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?

Given an output schema exists and return values need not be explained, the description covers everything an agent needs: prerequisites, fallback mechanics, failure code, and the related verification tool. For an explicitly experimental capability, the incompleteness is disclosed rather than hidden.

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 file_name, overwrite, confirm_overwrite, document_type, and survey_id are already fully documented in the schema. The description adds only the implicit .lss format and the export-directory location; the baseline 3 applies when structured fields do the heavy lifting.

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

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

The first sentence states a specific verb (export), resource (a survey's structure), format (.lss), destination (LIMESURVEY_EXPORT_DIR), and output shape (a path rather than base64). It is clearly distinguishable from the response-export siblings and from limesurvey_verify_survey_against_lss.

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 explicitly states the preconditions (LIMESURVEY_ENABLE_EXPERIMENTAL_METHODS=true, a plugin serving export_survey_structure/export_survey), the failure mode when unmet (EXPORT_UNSUPPORTED), and the alternative path (verify_survey_against_lss for read-only comparison). When-to-use, when-it-will-fail, and alternatives are all present.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered externally. The description adds genuinely non-redundant behavior: it names the underlying RemoteControl method and specifies that the configured service account handles auth so no session key should be passed — useful given sibling get_session_key/release_session_key exist.

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, zero filler, purpose front-loaded first, then implementation/auth detail. Every sentence conveys distinct information.

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

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

With an output schema present, return-value explanation is unnecessary, and the description correctly avoids it. It covers purpose, method provenance, and auth expectations for a 5-param read tool. It could add a note on what date formats are accepted (schema defers to 'accepted by LimeSurvey' vaguely), leaving a minor 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% and 2 of 5 parameters are enums with documented values, so the schema carries the parameter semantics. The description restates only the period (day/hour) already encoded in the enum and adds no format or syntax detail beyond it; 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: 'Return response counts by day or hour for a date range.' An agent can distinguish this from sibling export tools like export_statistics and get_summary by the day/hour aggregation framing. It does not name those siblings explicitly, 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?

Usage is implied by the 'date range plus day/hour period' framing, but the description names no alternatives and gives no explicit when-to-use or when-not-to-use condition. The one actionable directive is negative-auth ('do not provide a session key'), which is guidance but not tool-selection guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true; the description adds 'bounded client-side pagination', which is useful but minimal. No contradictions.

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

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

The description is a single, front-loaded sentence that conveys the core purpose efficiently. No wasted words.

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

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

For a simple tool with output schema, the description covers basic functionality but does not clarify what the output contains (e.g., list of survey objects) or the behavior of client-side pagination.

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

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

Schema coverage is only 33% (only query has a description). The description mentions 'by ID or title' but does not explain limit/offset semantics beyond the schema. With low schema coverage, more compensation was needed.

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 clearly states the tool finds visible surveys by ID or title with pagination, distinguishing it from the sibling 'list_surveys' which lists all surveys without search.

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

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

The description implies usage for search (by ID or title) but does not explicitly state when to use this over alternatives like 'list_surveys' or when not to use it.

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

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

Annotations already declare the safety profile (non-read-only, non-destructive, non-idempotent, closed-world), so the bar is lower. The description still adds real behavioral context: the ZIP is validated, it inherits the official Bootstrap 5 vanilla theme, and critically that the installed name is derived from the ZIP filename (dots stripped, 45-char cap), which an agent must know before uploading.

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 dense sentences, front-loaded with the deliverable and its version scope, followed by the naming rule and the upload instruction. No filler, though the installed-name formula appears twice (description and theme_name schema) without adding new information the second time.

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 description covers the artifact, naming derivation, and upload step. However, for a 23-parameter mutation tool with 13% schema coverage, it omits the overwrite/confirm_overwrite safety pairing and version-targeting semantics, leaving notable gaps for the caller.

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 only 13% across 23 parameters, so the description must compensate. It clarifies the two trickiest inputs, spelling out how theme_name plus theme_version map to installed_theme_name and citing the 45-character ceiling, but leaves overwrite/confirm_overwrite, target_limesurvey_major, and the styling parameters unexplained beyond their self-documenting defaults and patterns.

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 gives a specific verb and artifact ('Create a validated GPL-2.0-or-later ZIP theme') plus its inheritance basis (Bootstrap 5 vanilla theme) and target versions (LimeSurvey 7 or 6). This clearly separates it from siblings like limesurvey_validate_survey_theme and limesurvey_assign_survey_theme, which operate on themes rather than generating them.

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 implies a downstream workflow ('Upload the ZIP unrenamed and assign that name'), which points an agent toward the upload and theme-assignment tools, but it never states when to choose this tool over validate_survey_theme or how it relates to the publication guide. Usage is implied rather than explicit.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds useful auth context: it uses the configured service account and explicitly says not to provide a session key, which is valuable behavioral information beyond the annotations.

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

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

Two sentences, front-loaded with purpose, followed by method name and auth constraint. Every sentence earns its place with no redundancy.

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

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

Given a simple read-only tool with full schema coverage, rich annotations, and an output schema, the description covers purpose, method, and auth adequately. The main gap is not clarifying how this differs from the sibling 'limesurvey_get_site_settings', which could cause confusion.

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 (response_format) is fully documented with an enum and default. The description adds no additional parameter meaning, so the baseline of 3 applies per the rules.

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

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

States a specific verb ('List') and resource ('global setting names available to a super administrator'), and clarifies that it returns names, not values. However, it does not explicitly differentiate from the sibling 'limesurvey_get_site_settings', which likely returns actual settings, so an agent must infer the distinction from the word 'available'.

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 notes the tool is for super administrators and lists available setting names, which implies usage for discovery before setting values. But it provides no explicit when-to-use, when-not-to-use, or alternative tool guidance (e.g., versus get_site_settings).

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuine value beyond that by disclosing the RemoteControl method name and the service-account auth model with no session key required, which an agent needs to call it 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?

Three short sentences, front-loading the purpose before the method and auth notes. Every sentence earns its place, though there is minor redundancy between 'Return the ... field map' and the title.

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 not be described, and annotations cover safety. The description covers purpose, method, and auth, making it essentially complete, with only the lack of sibling routing as a minor 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 the parameters (survey_id, language, response_format) are fully documented in the schema. The description adds no parameter-level meaning beyond it, so the baseline 3 applies.

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

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

States a specific verb and resource ('Return the survey response field map'), which is clear and distinct from property getters like get_survey_properties. However, it does not explicitly differentiate itself from sibling read tools, so it stops 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?

Provides an authentication guideline ('do not provide a session key') which is useful context. But it gives no guidance on when to use this over alternatives like get_survey_properties or get_response_ids, leaving usage to inference.

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