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

The description goes beyond the read-only/idempotent annotations by explaining what statistics are returned per question type, that multi-select percentages are of respondents and can exceed 100%, and that data is loaded automatically if not cached. These are meaningful behavioral details not present in 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?

The description is well-structured and front-loaded with purpose, followed by useful output-type details and usage examples. The 'Args' section repeats schema information, adding some length, but the overall structure remains efficient and scannable.

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

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

With no output schema, the description compensates by detailing what is returned for categorical, numeric, date, and free-text questions. It also covers parameters, the optional restriction to chosen questions, the filter option, output formats, and the caching behavior, making it sufficiently complete for an agent to invoke 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 100%, so the schema already fully documents uid, columns, query, and response_format. The description restates the args without adding significant new parameter-level meaning, though the response_format enum is reinforced by the markdown/json mention.

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

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

The description opens with a specific verb and resource: 'Compute descriptive statistics for every question (or a chosen subset) of a form.' It lists the per-type outputs and explicitly contrasts with kobo_crosstab, making the tool's purpose distinguishable from its siblings.

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 provides concrete 'Use when' examples, such as 'What do the responses to my cocoa form look like?' and 'What's the average plot size?', and an explicit 'Don't use when' case referencing kobo_crosstab. This gives an agent clear selection criteria.

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

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

Beyond the annotations (which already indicate not read-only, not destructive, and idempotent), the description adds useful behavioral context: responses are kept, remain exportable, and archived forms can be reactivated. It also states the return value as deployment status. No contradictions with annotations.

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

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

The description is well-structured and efficient: it front-loads the core action and safety property, gives a clear usage directive with the alternative, then lists parameters and return value. Every sentence earns its place without unnecessary detail.

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

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

For a simple two-parameter tool with full schema coverage and no output schema, the description is complete: it explains the effect, the alternative, the parameters, and the return value. The safety profile is also covered by annotations, so nothing essential is missing.

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

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

Schema description coverage is 100%, and the description's Args section largely repeats the schema's parameter documentation. The active parameter's meaning is fully covered in the schema, so the description adds no significant new semantic value beyond what is already structured.

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 a specific verb ('archive or reactivate') and resource ('KoboToolBox form'), and clearly states what the tool does: stops new submissions without deleting data or brings an archived form back. It also explicitly differentiates from kobo_delete_form, making its purpose unambiguous.

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

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

The description gives direct when-to-use guidance: it is 'the correct way to end a data collection round' and should be used 'instead of kobo_delete_form, which destroys the data.' This explicitly names the alternative and the reason for preferring this tool.

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

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

The description discloses behaviors far beyond annotations: files are saved to disk, every figure is computed server-side from real submissions, cross-tabs are delivered as computed tables rather than live PivotTable objects, and the 'custom' source must not be used for figures the server can derive. It even explains the named Excel Table's purpose for enabling user-created pivots. This is unusually transparent.

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 long, but the tool is complex and the length is earned: purpose is front-loaded, then directive syntax, workbook contents, pivot limitation, and a clear 'Run kobo_load_data first' instruction. It is well-structured and every section serves a practical purpose, though a slightly tighter phrasing would improve scannability.

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 12-parameter report builder with no output schema, the description covers the critical operational details: what the workbook contains, how visuals are declared, the custom-table restriction, the pivot-table limitation, the max_rows memory protection, and the return value (full path of each generated file). Nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful guidance beyond the schema: the visual directive format with examples, the rule that 'custom' is only for figures the server cannot derive, and the warning never to type counts or percentages into custom tables. This supplements the already-complete schema effectively.

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

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

The description opens with a specific verb and resource: 'Produce finished deliverables from a form's data: an analytical Excel workbook, a written Word report, and/or a PDF — saved to disk.' It clearly distinguishes this tool from sibling raw-data/export/analysis tools by emphasizing finished deliverables with written analysis plus server-computed visuals.

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

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

It gives clear context for when to use the tool ('Produce finished deliverables') and an explicit workflow prerequisite: 'Run kobo_load_data first so you know which questions exist and what shape the data is in.' It does not explicitly name alternatives or exclusions, but the context is strong enough that an agent can identify the right 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?

Annotations already cover the mutation (readOnlyHint=false) and non-destructive nature (destructiveHint=false). The description adds useful context: it creates a new project, omits submissions, and supports optional immediate deployment via the deploy param. This goes beyond the bare annotation flags and clarifies the tool's 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?

The description is front-loaded with the core behavior, followed by usage guidance, parameters, and return info. Each sentence adds value, with no filler. The structure makes it easy for an agent to scan and extract the key facts quickly.

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 relatively simple tool with three flat params and no output schema, the description covers the essential behavior, the return value (uid and status), and the optional deploy action. It doesn't address edge cases like whether the original form is ever modified or what 'status' means exactly, but those are minor gaps given the annotations and simple parameter surface.

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 input schema fully documents all three parameters. The description's Args section repeats the schema rather than adding new semantic details. It does, however, reinforce the default for name and the boolean meaning of deploy, but that's marginal beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb (copy) and resource (existing form's structure) with an explicit outcome (brand-new project, no submissions). It clearly distinguishes this from siblings like kobo_create_form (create from scratch) and kobo_import_xlsform (import) by describing the clone behavior.

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 concrete use cases ('reuse a questionnaire for a new round, region or season', 'experiment on a copy instead of a live form'), which clearly imply when to choose this tool. It does not name specific alternatives or state when not to use it, but the context is strong enough for correct selection.

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

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

The annotations already mark the operation as non-read-only and non-idempotent, and the description adds concrete behavioral context: creating versus deploying, the flat-list balance requirement, local validation before any request reaches Kobo, and the return value (uid, deployment status, public collect links). No annotation contradiction is present.

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

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

The description is long but every section earns its place: purpose, flat-list warning, condensed args, return values, concrete examples, explicit alternative routing, and error handling. It is front-loaded with the core action and uses headers and lists so an agent can scan it quickly.

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 form-creation tool with no output schema, the description provides the essential missing pieces: return shape, deployment behavior, local validation semantics, and representative usage. The rich input schema handles the per-field details, and the description fills the operational context around it.

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 schema carries most parameter definitions; the description adds value by showing complete question examples (grouping, relevant skip logic, constraint messages, repeat rows), the multilingual label form, and the explicit phonenumber spelling warning. This goes beyond a bare schema listing, though it does repeat several 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 first sentence states a specific action ('Create a new form (survey)') on a specific resource, with a precise input ('from a list of questions') and an optional behavioral toggle ('optionally deploy it immediately'). It later explicitly routes edits to kobo_patch_form and kobo_update_form, so it is clearly distinguished from the update siblings.

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 an explicit 'Don't use when' section: if the goal is to change an existing form, use kobo_patch_form for targeted edits or kobo_update_form to replace everything. It also clarifies the deploy flag choice between immediate collection and leaving a draft, giving the agent a clear decision rule.

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

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

Annotations already establish readOnly, idempotent, open-world, and non-destructive behavior, so the description does not need to repeat those. It adds useful behavioral context by stating that the return includes row, column, and grand totals plus the count of submissions excluded for missing either answer. No contradictions with the annotations are present.

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

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

The description is well-structured with an intro, Args list, Returns, and Use-when examples, and the key purpose is front-loaded. Some parameter details in the Args list duplicate the schema, but the examples and returns keep the description from feeling 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?

Given the tool's moderate complexity, seven parameters, and no output schema, the description provides enough context: return shape, exclusion behavior, metric meanings, and realistic examples. It could be more explicit about how percentages are calculated or how missing-answer submissions affect totals, but the core information an agent needs to invoke it correctly is present.

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

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

The input schema already documents all seven parameters at 100% coverage, setting a baseline of 3. The description adds value with concrete example parameter combinations and clarifies how metrics like row_pct and mean are used in practice. It does not dramatically enrich every parameter, but the examples improve selection confidence.

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: “Cross two questions to see how answers to one vary with the other.” This clearly identifies a cross-tabulation operation on KoboToolbox questionnaire data and is distinct from the sibling tools, none of which describe this analytic operation.

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 “Use when” examples map natural-language analytical questions to concrete parameter choices, such as row_column, col_column, metric, and value_column. This gives clear contextual guidance, though it does not explicitly say when NOT to use this tool or name an alternative to prefer.

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 discloses the permanent, destructive nature of the operation, including that submissions are deleted too and that the action cannot be undone. This goes beyond the destructiveHint annotation by specifying the exact data-loss scope and the confirmation safeguard.

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 concise, front-loads the critical warning, uses a clear argument list, and ends with a practical alternative. Every sentence earns its place without unnecessary filler.

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

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

For a destructive tool with no output schema, the description fully covers the operation's consequences, the required confirmation parameters, the submission-count safeguard, and the appropriate alternative. An agent has enough context to invoke it safely.

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

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

The input schema already has 100% description coverage for all parameters, so the baseline is 3. The tool description mostly restates the schema's parameter explanations without adding new semantic detail or clarifying constraints beyond what is already present.

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 a specific verb ('delete'), names the resource ('form'), and explicitly includes all submissions with irreversible consequences. It also distinguishes itself from the sibling kobo_archive_form, so the agent can tell them apart immediately.

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

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

It gives an explicit when-not-to-use rule: 'Don't use when: you just want to stop collecting data. Use kobo_archive_form instead — it keeps every response.' This clearly routes agents away from destructive deletion when archiving is the intended behavior.

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 mark destructiveHint=true and readOnlyHint=false; the description adds the irreversible nature ('THIS CANNOT BE UNDONE') and clarifies exactly what is destroyed (specific submissions, not the whole form). This adds useful context 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?

Well-structured and front-loaded with the critical warning, then use cases, parameters, and exclusions. Every sentence earns its place and the description is compact without 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?

For a 3-parameter tool with no output schema, the description covers purpose, parameter provenance, required confirm flag, alternatives, and destructive consequences. Nothing essential for an agent to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds extra meaning by telling the agent that submission_ids should be the '_id' values from kobo_list_submissions and that confirm must be explicitly true, going beyond the schema text.

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

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

States a precise verb and resource: 'Permanently delete specific submissions from a form.' It clearly distinguishes itself from sibling kobo_delete_form (whole form deletion) and kobo_validate_submissions (flagging instead of deleting), so an agent can tell them apart.

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

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

Explicitly lists when to use it: remove test entries, duplicates, or a withdrawal request. It also gives explicit 'Don't use when' conditions with named alternatives, leaving no ambiguity about tool selection.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, and the description adds meaningful behavioral context beyond that: deploying makes the form live but NOT public, and the Enketo link requires a Kobo login until sharing is enabled. This clarifies side effects and access behavior without contradicting 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?

The description is compact and well-structured with clear sections for behavior, arguments, return value, and a relevant caveat. It is front-loaded with the main purpose and every sentence adds useful information without unnecessary elaboration.

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 one simple parameter, no output schema, and annotations already covering safety, the description is nearly complete. It explains the return value (deployment status and collect links) and the important privacy/auth caveat. It could add slightly more detail on what deployment statuses look like, but nothing critical is missing for selecting and invoking 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?

There is only one parameter, uid, and the input schema already describes it as the asset uid of the form to deploy. The description repeats this in the Args section but adds no new semantic detail, so with 100% schema coverage the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: deploy a draft form or redeploy a changed one so it becomes active and can collect submissions. It names the specific resource type (KoboToolbox form) and the action (deploy), which distinguishes it from siblings like kobo_update_form, kobo_archive_form, and kobo_get_form.

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

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

The description provides clear context for when to use the tool: when a draft or changed form needs to be made active. It also gives a practical exclusion note, directing users to kobo_set_sharing when anonymous submissions are needed. However, it does not explicitly describe when not to deploy or contrast with all alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds that it only returns pass/fail lines and exact fix commands, not performing fixes itself, which is useful behavioral context 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?

Three short sentences front-load the purpose, then give usage timing and return format. Every sentence earns its place with no filler.

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

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

For a simple diagnostic tool with one optional parameter, the description covers what it checks, when to run it, and what it returns. Annotations cover safety, and the parameter is fully specified by the schema.

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

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

Schema description coverage is 0% and the description does not mention the response_format parameter at all. While the schema's enum and default make the parameter self-documenting, the low coverage means the description was expected to compensate and doesn't.

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 the specific verb 'Diagnose' and names concrete configuration items: Kobo connection, API token, output directory, and Python report renderer. This clearly distinguishes the tool from sibling form/submission operations.

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 explicit when-to-use instructions: run it first when a tool fails for an unclear reason or right after installing the server. It doesn't state when not to use it or name alternatives, but as a dedicated diagnostic tool this is clear context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description is not required to repeat those. It adds useful behavioral context: files are fetched to disk organized per submission, there is a safety cap (max_files), and the return includes the directory written, file count, and total size. This goes beyond the schema by describing the operational outcome. It doesn't discuss error handling or edge cases, but given annotation coverage, a 4 is appropriate.

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 well-organized: a one-sentence purpose, a motivational paragraph, and an Args/Returns breakdown. Every sentence is informative, with no fluff or redundancy. The default output directory is explained clearly, and the overall length is appropriate for the tool's complexity. The structure is front-loaded with the essential purpose.

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

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

The tool is moderately complex (4 parameters, multiple behaviors), but the description, together with the schema and annotations, provides everything an agent needs: clear purpose, parameter semantics, default behaviors, return values, and safety hints. The absence of an output schema is compensated by the explicit Returns line. No critical information is missing for correct invocation.

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

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

The input schema has 100% coverage, with each parameter described (e.g., 'Asset uid of the form', 'Directory to write the files into'). The description mirrors these descriptions without adding new semantic details; it restates defaults and the output directory pattern that are already in the schema. It does not, for example, clarify format of submission IDs or interactions between params. With high schema coverage, the baseline of 3 applies, and the description adds little beyond it.

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

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

The description opens with a specific verb and object: 'Download the photos, audio, video and files attached to submissions.' It clearly identifies the resource (KoboToolbox attachments) and distinguishes itself from siblings like kobo_export_submissions_excel (which exports Excel, not files) and kobo_list_submissions (which lists metadata). The motivation ('nothing in an Excel export contains them — only file names') further clarifies what this tool uniquely does.

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 a clear rationale for when to use this tool: when you need actual attachment files, not just names from an Excel export. It implicitly contrasts with the Excel export sibling. However, it does not explicitly name alternative tools or state when NOT to use it, though the context makes the intended use obvious. This earns a 4 rather than 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 provide readOnlyHint and destructiveHint, and the description adds meaningful operational context: it triggers a fresh export server-side, waits up to ~90s, downloads the result, and returns it in an embeddable base64 form. The 90s timeout behavior is a key non-obvious trait that the agent needs to know.

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 structured with a clear opening summary followed by Args, Returns, usage examples, and Error Handling. Every section earns its place, the main behavior is front-loaded, and no filler or redundant restatement of the title is present.

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

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

For a tool with no output schema, the description fully explains the return value: embedded base64 file, size, and download URL. It also covers the failure mode for large forms and advises checking the Kobo web UI, so an agent can set expectations and recover from timeouts.

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 extra value by telling the agent where to get the uid ('from kobo_list_forms') and clarifying the optional language parameter's effect on multilingual form column headers. These are small but genuinely useful additions beyond the schema.

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

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

States a specific verb ('Generate... export') and a concrete resource ('all submissions for a form'), with both supported formats named. It also distinguishes the tool from the submission-reading sibling by explicitly saying when not to use it.

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 explicit use cases with a concrete example ('Give me an Excel file...') and a clear exclusion ('Don't use when... use kobo_list_submissions instead'). The agent is told both when and when not to invoke this tool, and which alternative to pick.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond that: the output is a real .xlsx workbook in the standard exchange format, and the function returns the written path and its size. No contradiction with annotations exists.

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

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

The description is concise and well-structured: purpose first, then usage context, then arguments and return value. Every sentence contributes meaningful information, and there is no fluff or repetition beyond an acceptable argument summary.

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 two-parameter export tool with rich annotations, the description is complete: it explains what is produced, why to use it, which sibling tool handles the reverse operation, what the arguments mean, and what is returned. No critical operational information appears to be 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 both uid and output_path are already documented. The description restates their meaning but adds little beyond the schema; it does clarify the return value, but that is output behavior rather than parameter 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 the tool downloads a form as a real XLSForm .xlsx workbook, the standard ODK/Kobo exchange format. It uses a specific verb and resource and distinguishes itself from siblings by emphasizing the XLSForm deliverable and by mentioning re-import with kobo_import_xlsform.

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 concrete use cases: sharing the questionnaire, version control, Excel editing, and re-importing elsewhere. It names kobo_import_xlsform as the complementary tool, which provides useful routing context, though it does not explicitly state when not to use it or compare it to kobo_get_form.

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 signal read/write safety and destructiveness, and the description adds valuable behavioral detail beyond them: rollback changes form structure only, collected submissions remain, and fields that no longer exist drop out of exports. This is exactly the kind of side-effect disclosure that lets an agent reason about consequences.

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 well structured and front-loaded with the core purpose. The use-case explanation and notes earn their place, and the Args/Returns/Notes sections are scannable. The Args list is slightly redundant with the schema but remains compact and helpful.

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

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

With no output schema, the description compensates by stating the return format, ordering ('newest first'), deployment dates, and post-rollback status. It also covers the main side effect and the optional-parameter behavior. The only things not spelled out, such as error conditions, are minor given the annotation coverage and schema richness.

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

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

The input schema already describes all four parameters with 100% coverage)Skip, so the description's Args section mostly repeats structured information. It adds minimal extra meaning beyond the schema, such as the implication that omitting rollback_to lists history, which the schema itself already conveys.

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 two concrete verbs and a specific resource: 'List a form's deployed versions, and roll back to one of them.' This clearly distinguishes it from sibling functions that manage forms generically, and the rollback capability is unique among the listed tools.

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

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

It gives an explicit, scenario-based 'when to use' instruction: 'the way back when a change breaks a live form.' It explains how it differs from a plain update by restoring old structure without touching collected submissions. It stops short of naming specific alternative tools or stating when not to use it, so it does not fully earn 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 establish read-only, idempotent, non-destructive behavior. The description adds valuable behavior beyond that by enumerating every returned link type (offline, online, single, preview, iframe) and revealing that the tool also reports the form's public-facing login requirement.

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

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

The purpose is front-loaded, and bullet lists make the five return variants and the QR/format arguments easy to scan. The Args section partially duplicates the schema, so not every line earns its place, but the size is still reasonable for a tool with no output schema.

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

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

Since there is no output schema, the description fully carries the responsibility of describing return content. It explains the five URL types, the public/login caveat, the optional QR image, and the response_format choices, which is sufficient for an agent to call 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 100%, so the baseline is 3 and the description only needs to add marginal value. It repeats the uid, include_qr, and response_format details almost exactly as the schema does, with only a small addition like printing the QR code on a flyer.

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

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

The description opens with a specific verb and resource ('Get the shareable links of a deployed form') and clarifies this is the final deliverable once a form is built. It enumerates all five Enketo URL variants so there is no confusion about what the tool produces, and it explicitly points to kobo_set_sharing for the related but different task of enabling anonymous access.

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 tells the agent this is the tool to use after a form is deployed and for distributing links to field teams, while also giving one explicit alternative: use kobo_set_sharing to make a form genuinely public. It lacks a broader when-not-to-use statement against all sibling tools, so it is not a full routing guide.

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, and destructiveHint=false. The description adds meaningful behavior beyond those: rows are cleaned, labels replace codes, the query is a Mongo-style server-side filter, and output can be markdown or JSON. It doesn't cover auth or error behavior, but the annotation base makes that a minor 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?

The description is compact and well-ordered: purpose first, then usage guidance, then a concise Args list. Every sentence earns its place and no filler or repetition of annotations is present.

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

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

For a read-only sampling tool with full schema coverage, the description covers the purpose, use cases, alternatives, parameter constraints, and output format. The only real gap is the absence of a return-structure definition or error conditions, but 'cleaned rows' plus response_format gives enough for a competent agent to call it correctly.

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

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

Schema description coverage is 100%, so the input schema already documents every parameter clearly, including examples for query. The Args section in the description mostly restates the schema without adding new semantics, so the baseline of 3 is appropriate.

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

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

The description states a specific action and resource: 'Return actual cleaned rows of the dataset, with labels rather than codes.' It also names concrete use cases (reading open-ended answers, sanity-checking, inspecting records) and explicitly distinguishes itself from kobo_analyze/kobo_crosstab.

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 explicit when-to-use guidance ('read open-ended answers, sanity-check the data before drawing conclusions, or inspect specific records') and when-not-to-use guidance ('For aggregate figures prefer kobo_analyze or kobo_crosstab'). This leaves little ambiguity about tool selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it details what is returned (deployment status, submission count, available languages, annotated question outline) and documents the not-found error condition, including the token-access caveat.

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 front-loaded with the core purpose, then organized into Args, Returns, and Error Handling sections. Every sentence adds useful information and there is no filler or redundancy with the annotations. The length is appropriate for the tool's 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?

For a read-only retrieval tool with no output schema, the description covers invocation inputs, the shape of the response, and the primary error case. It also explains how multilingual forms and response formats behave, which is enough for an agent to call the tool correctly and interpret its result.

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

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

Schema description coverage is 100%, so the schema already explains all three parameters. The description largely restates the schema's parameter meanings rather than adding new semantic depth, though it does reinforce the 'from kobo_list_forms' provenance and the markdown/json distinction. This matches the baseline for fully documented schemas.

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 begins with a specific verb and resource: 'Get full details of a single form', and enumerates its distinctive content (question structure, section nesting, skip logic, validation rules). This is clearly not a list-forms operation, but it does not explicitly differentiate itself from closely related siblings such as kobo_export_xlsform or kobo_form_versions.

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 intended use is implied through the return-value description and the hint that the uid should come from kobo_list_forms, so an agent can infer it is for inspecting a single form's detailed structure. However, the description gives no explicit when-to-use guidance, exclusions, or alternatives, leaving the choice against sibling tools like kobo_export_xlsform to the agent's inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, read-only operation. The description adds that it returns 'every field and value recorded,' which is useful but not rich detail about potential errors, response format behavior, or prerequisite authentication. Since annotations cover safety, a 3 reflects that the description adds only modest behavioral context.

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

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

The description is compact: one purpose sentence, a brief parameter list, and a return statement. It's front-loaded with the primary purpose and uses clear structure. No filler or redundant elaboration exists, so 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 single-submission getter with read-only annotations and 100% schema coverage, the description provides enough to call it correctly: it explains the return content, the source of submission_id, and the response_format options. It doesn't mention error cases or output structure, but given the simplicity and prior tool usage hint, it's adequately complete. A 4 reflects that minor gaps like error handling are not critical.

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 descriptions cover 100% of the parameters, each with clear explanations (e.g., uid is 'Asset uid of the form', submission_id is 'Submission id (from kobo_list_submissions)'). The description restates these in an 'Args' list but adds no new semantic meaning beyond what the schema already provides. With full schema coverage, the baseline 3 applies.

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

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

The description opens with 'Get the full detail of one submission by its id,' which is a specific verb–resource pairing that clearly distinguishes it from sibling tools like kobo_list_submissions (which lists many submissions). It also states the expected return ('every field and value recorded'), making the tool's exact purpose unmistakable.

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 references that submission_id comes from kobo_list_submissions, implicitly guiding the agent to first list submissions and then fetch one by its '_id'. However, it does not explicitly state when to prefer this tool over alternatives like kobo_export_submissions_excel or kobo_get_data_sample. This is clear context but lacks explicit exclusions, so a 4 is appropriate.

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 mark this as destructive and non-read-only. The description adds value by clarifying the overwrite behavior, the deploy option, and server-side XLSForm validation with row/column error reporting. No contradiction with annotations.

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

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

The description is well-structured with a clear intro, usage guidance, args, returns, and error handling. Every section contributes useful information and the key purpose is front-loaded.

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

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

With no output schema, the description compensates by stating the return value (form uid and import status) and error behavior. It is sufficient for invoking the tool, though the exact shape of 'import status' and any deploy side effects are not detailed.

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's Args section largely restates the schema rather than adding extra examples, types, or edge-case details, so it adds minimal value beyond the structured definition.

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: 'Upload an XLSForm .xlsx workbook to Kobo'. It also distinguishes two clear modes (new form vs overwrite existing), which separates it from siblings like export_xlsform, create_form, and deploy_form.

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

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

It gives clear usage context: use when a questionnaire already exists as a spreadsheet or to round-trip a form edited in Excel. However, it does not explicitly name alternatives or state when not to use this tool versus the other form-creation siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: the tool only returns forms accessible with the configured token, never submission data, and returns specific fields (uid, name, deployment status, submission count). This goes beyond the structured metadata.

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 compact and well-structured: a one-line purpose, a critical exclusion, a brief Args list, a Returns summary, and practical examples. It is front-loaded with the most important semantic distinction and contains minimal 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?

For a read-only listing tool with no output schema, the description is complete: it covers auth scope, parameter behavior, output fields, exclusions, and example invocations. Pagination and limits are documented in the schema, and the description tells the agent what output to expect. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters and their constraints. The description's Args section adds no meaning beyond what the schema provides, though the 'search' example in the usage section does illustrate how to apply the filter. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'List forms/projects (surveys) accessible with the configured API token.' It clearly separates this from kobo_get_form (single form) and kobo_list_submissions (submission data), so an agent can tell exactly what the tool returns.

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 explicitly states what the tool is NOT for and names the alternative: 'Does NOT return submission data — use kobo_list_submissions for that.' It also provides concrete use-case examples such as 'What forms do I have on Kobo?' and 'Find my cocoa tracking form', which map directly to parameter usage.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: most-recent-first ordering, optional Mongo-style query filtering, pagination via offset, and the return shape (submission id, submission time, answered fields). These go beyond the annotations and schema.

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

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

The description is well-structured with Args, Returns, and Examples sections, and the purpose is front-loaded in the first sentence. It is somewhat longer than necessary because the Args block repeats schema descriptions, but the examples and explicit usage guidance earn their 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?

With no output schema, the description correctly states the return fields. It also covers ordering, query filtering, pagination, response format, and the main alternative tool. For a read-only list operation with rich annotations, nothing essential is missing for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema fully documents all five parameters. The description largely duplicates schema information in the Args block, but it adds a practical example for the query parameter ('crop_health':'poor') and the 'latest 10 responses' use case. This gives a baseline-appropriate 3 with only modest added meaning.

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

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

The description opens with a specific verb and resource: 'List submitted responses for a form, most recent first.' It distinguishes itself from siblings by being a plural list operation versus kobo_get_submission, and by explicitly contrasting with kobo_export_submissions_excel for downloadable output. The scope is immediately clear.

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 explicit 'Use when' examples for two common agent intents and an explicit 'Don't use when' case that names the correct alternative tool. This gives clear selection criteria relative to sibling 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?

Beyond the annotations, the description discloses meaningful behavior: it downloads all submissions, applies transformations (choice labels, number/date conversion, group flattening), caches the result for 15 minutes, and reports data quality. It also explains that the cache is reused by other tools and that refresh forces a re-download. No contradiction with the readOnly/idempotent annotations exists.

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

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

The description is longer than average but well-structured: purpose is front-loaded, the sibling distinction comes second, then args, then return value and usage hint. The Args list duplicates some schema information, but it interleaves practical context that helps an agent, so the length is mostly earned and not 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?

With no output schema, the description adequately explains the return shape: analysable questions with measurement types and answer options, submission count, and a data-quality summary. It also tells the agent how to use the returned 'field' values with other tools, which is exactly the guidance needed for correct follow-up calls. Nothing essential is missing for a read-only cached data-loading tool.

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

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

Schema coverage is 100%, so the input schema already documents all six parameters. The description adds modest context such as max_rows being a 'safety cap' and the returned field values being what to pass to other tools, but it largely restates the schema rather than adding substantial new parameter meaning. The phrase 'default: everything, up to 50000' is also slightly ambiguous compared to the schema's explicit default of 50000.

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

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

The description opens with a specific verb and resource: 'Download ALL submissions of a form and prepare them for analysis.' It clearly distinguishes this from kobo_list_submissions by contrasting 'one page of raw records' with the full cleaned dataset, and it names the exact downstream tools that consume the result.

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 explicitly says 'Start every analysis here,' which is a strong directive for when to use the tool. It also names kobo_list_submissions as the alternative for single-page raw records and lists which sibling tools consume the cached snapshot, making the surrounding workflow unambiguous.

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 already marking the tool as destructive and non-read-only, the description adds valuable nuance: 'everything not named is left exactly as it is', removing a group removes its contents, empty strings clear skip logic/constraints, and redeploy defaults to true. It also discloses that a per-change report of applied and unfound changes is returned.

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 well-structured: a brief purpose statement, a safety guarantee, a compact bullet list of all nine parameters with inline semantics, a return-value note, and three practical examples. There is no filler, and the length is justified by the number of parameters.

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, nine-parameter tool with no output schema, this is unusually complete: every operation is explained, return behavior is summarized, and examples show exact usage. It falls just short of excellent by mislabeling uid as optional and by not explicitly naming the full-update sibling tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful semantics like empty-string clearing, append-only choices, and group-removal behavior, plus concrete examples. However, the header 'Args (all optional, combine freely)' is inaccurate because uid is required by the schema, which prevents a higher score.

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 ('Make targeted changes to an existing form') and immediately differentiates from a full resend of the question list. It clearly names concrete use cases like fixing a typo, adding a choice, or attaching skip logic, making its purpose unmistakable.

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

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

It gives clear context for when to use the tool: targeted changes to a form that is already collecting data, without resending the whole question list. However, it does not explicitly name kobo_update_form as the alternative for wholesale form updates, so the exclusion is implied rather than stated.

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

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

Despite annotations already covering destructiveHint and readOnlyHint, the description adds valuable behavioral context: anonymous_submissions never exposes existing responses to the public, only allows new submissions; revoke_from removes every permission a user holds; and publishing is outward-facing and should be confirmed with the user. These details go beyond the annotations and give an agent a solid mental model of the tool's 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?

The description is well-structured with clear sections (purpose, mechanisms, roles, args, returns, examples, notes) and front-loads the core purpose. It is somewhat long, and the Args section largely repeats the input schema's descriptions, which is redundant. Overall, the organization earns its place, but tightening the redundant parts would make it stronger.

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

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

For a tool with no output schema, the description explicitly states what it returns (the resulting access list and collect links when public), making agent expectations clear. It covers all five parameters, gives role semantics, includes examples, and highlights the one risky behavior (public publishing) with a confirmation note. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, which sets the baseline at 3. The description still adds meaningful semantics: it explains that anonymous_submissions is what turns a deployed form into a genuinely public link, clarifies the role hierarchy, and provides concrete examples that map user intents to specific parameter values. This goes beyond simply restating the schema, though the Args section does partially duplicate schema text.

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

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

The description opens with a specific verb and resource: 'Control who can fill in a form and who can work on it.' It then breaks the purpose into two concrete, distinct mechanisms (anonymous_submissions vs. share_with/revoke_from), which clearly separates it from siblings like kobo_update_form (editing form content) or kobo_deploy_form (deployment). This is an unambiguous, well-differentiated statement of what the tool does.

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 makes the usage context clear through the two-mechanism breakdown, role definitions, and concrete examples mapping natural-language requests to argument values. It also includes an important caution to confirm before enabling public submissions. However, it does not explicitly name alternatives or state when not to use this tool versus related ones, so it falls just short of the top score.

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

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

Annotations already indicate a write operation (readOnlyHint=false), but the description adds critical behavioral context: submitted rows are real data and count toward the form's submission total, repeated submissions create duplicates, attachments cannot be sent, and rejected submissions usually indicate invalid field paths. This goes well beyond the annotation signals.

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 organized into Args, Returns, Notes, and Error Handling, with the primary purpose front-loaded. Every section earns its place: parameter formats, side effects, exclusions, and failure diagnosis are all actionable and non-redundant.

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

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

With no output schema, the description correctly states the return value ('the instance id Kobo assigned'). It also covers the most likely failure mode, the real-data consequence, and the unsupported attachment case. For a mutation tool with nested parameters and side effects, nothing essential is missing.

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

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

Although schema coverage is 100%, the description adds meaning the schema lacks: exact answer-path conventions for nested groups, space-separated select_multiple codes, ISO date format, geopoint format, and the explicit use of count for load-testing only. These practical examples help an agent construct valid parameter values more reliably than the schema alone.

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

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

The description opens with a specific verb and resource: 'Send a response to a deployed form through the API, without going through the web form.' This clearly distinguishes the tool from web-form submission and from sibling read/export tools like kobo_get_form, kobo_list_submissions, and kobo_get_submission.

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

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

The description gives explicit when-to-use guidance: test a form end-to-end before sending enumerators, or migrate paper/spreadsheet answers. It also states exclusions and alternatives: attachments must use the web form, and test rows should be deleted with kobo_delete_submissions. This fully routes an agent to the correct tool and follow-up actions.

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 readOnlyHint=false, but the description adds concrete consequences: submissions are preserved while answers to removed questions become orphaned and disappear from exports, and validation happens locally. This goes beyond the structured hints, though it doesn't cover authentication or failure modes.

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

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

The description front-loads the core action and the sibling differentiation, then uses a clean Args/Notes structure. It is somewhat lengthy, but each section earns its place by communicating destructive behavior, safety conditions, and alternative routing.

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 4-parameter tool with a fully detailed input schema, the description covers high-level behavior, data consequences, and tool selection guidance. There is no output schema, so return values needn't be described; an agent has everything needed to invoke it safely.

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 each parameter is already thoroughly documented in the schema. The description reinforces the critical 'left-out questions are removed' semantics but adds no new meaning beyond the property descriptions, so the baseline 3 is appropriate.

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

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

The description opens with a precise statement: 'Replace the ENTIRE question list of an existing form with a new one.' The explicit emphasis on 'ENTIRE' and the contrast with kobo_patch_form immediately distinguish this destructive full-replacement tool from its sibling for targeted edits.

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?

Guidance is explicit: 'Prefer kobo_patch_form for targeted edits... it leaves the rest of the form untouched and cannot accidentally drop questions.' It also explains when confirm_replace is required and what redeploy does, so an agent knows both when to use this tool and when to avoid 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 indicate destructiveHint=false and idempotentHint=true, and the description adds valuable non-destructive behavioral detail: the row remains in the database and exports with its status rather than being removed. It also discloses the return value (count of updated submissions), which the annotations do not provide.

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

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

The description is compact and well-structured: a one-line purpose, a one-sentence behavioral clarification, a concise Args list, and a Returns note. No filler or redundant restatement of the tool name or 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?

For a straightforward 3-parameter mutation tool with no output schema, the description is complete: it explains what the tool does, why it exists, how to supply parameters, and what the caller receives in return. The annotations cover idempotency and non-destructiveness, so no critical operational context 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. The description adds useful clarification beyond the schema by specifying submission_ids are the '_id' values to mark and enumerating the exact allowed status strings. This helps the agent construct the correct request without needing to infer semantics from the generic 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 opens with a specific verb and resource: 'Mark submissions as approved, not approved, or on hold.' It clearly identifies the operation (setting validation status) and distinguishes it from sibling tools like kobo_delete_submissions by noting this is non-destructive and preserves the row in the database and exports.

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 explicitly frames the tool as the non-destructive way to handle suspect responses and contrasts it with deletion: 'the row stays in the database and in exports, carrying its status, instead of being deleted.' This gives the agent a clear when-to-use and when-not-to-use signal relative to destructive alternatives.

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