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

Given annotations only declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description adds substantial behavioral context: hosted download URL secrecy, expiry/max_uses semantics, local file writing with overwrite behavior, size-check-before-export, and the advisory nature of confirm_size_bytes. It also warns against splitting refused requests. 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 front-loaded with the core purpose and mode-dependent behavior, and every paragraph carries operational weight (size caps, secret handling, refusal conditions). It is however quite long and dense for a tool description; a bullet or table structure for hosted vs local differences could improve scanability without losing content.

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

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

Given 25 parameters, an output schema (so return values need not be described), and the complexity of dual hosted/local behavior, the description covers all critical decision points: environment-dependent behavior, size confirmation, variable resolution, and refusal conditions. Nothing an agent needs in order to call it correctly or handle its response appears missing.

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

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

With schema description coverage at 100%, the baseline would be 3, but the description adds cross-parameter semantics not captured per-parameter in the schema: hosted vs local effects on `path` and `format`, the interaction of `limit` with `time_resolution`/`aggregate_operations`, and CF standard_name resolution for `variables`. These are meaningful additions beyond the schema, though many individual parameters (bbox, times, levels) are still only explained in 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 opens with a specific verb+resource: 'Export the FULL result of a query' and immediately differentiates itself by stating 'the data never enters the conversation'. This clearly distinguishes it from sibling tools like datamesh_query_data that presumably return data in-conversation. An agent can tell what this tool does without opening the schema.

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

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

The description gives rich context on when behavior changes (hosted vs local), when `path` is required or ignored, and when `confirm_size_bytes` is needed, including 'ask the user first'. It provides explicit refusal conditions (hosted cap, limit combined with resampling) but does not explicitly name an alternative sibling (e.g., datamesh_query_data or stage_query) for routine retrieval, leaving the when-to-use-this-vs-that inference to the reader.

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

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

With readOnlyHint and openWorldHint already provided, the description adds significant behavioral context beyond annotations. It explains that the default view reduces fields, clips long values, caps global attributes, and may shed attributes on very large records while always listing every variable 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?

The purpose is front-loaded in the first sentence, and the second paragraph is dense but every clause explains useful truncation behavior. There is no redundant or filler text.

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

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

The tool has an output schema and annotations covering safety and openness, and the description supplies the missing behavioral details about truncation and large-record handling. An agent has enough information to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description nonetheless adds meaning about what the default/summary view actually returns, especially truncation and field reduction, beyond the enum descriptions in 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: getting metadata for one datasource, including coverage, coordinates and variables. It is clear enough to distinguish this from sibling query/load/search tools, but it does not explicitly name or contrast 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?

Usage is implied by the purpose: use this to retrieve metadata for a known datasource. The description does not explicitly say when to choose this over siblings such as datamesh_search_catalog or datamesh_query_data, nor does it state prerequisites.

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

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

Adds real behavioral context beyond the readOnlyHint/openWorldHint annotations: gridded sources open lazily with no data download, tabular sources download only under an inline size limit, and oversize tabular data must go through query_data. It does not quantify the limit or describe failure behavior when a tabular source is too large and no query is issued.

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

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

Three tight sentences, front-loaded with the core action, then the type-specific behavior and the fallback path. No filler or restatement of the name.

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 explained, and the description covers both datasource classes and the oversize fallback. The only remaining gap is the unquantified size limit and what a caller observes when a tabular source is skipped.

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

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

Schema description coverage is 100% for the single datasource_id parameter, so the baseline is 3. The description adds no syntax, format, or ID-provenance detail beyond what the schema already documents.

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

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

States a specific verb+resource ("Summarize an entire datasource") and further splits behavior by datasource type (gridded vs tabular), which lets an agent scope it precisely. It names the sibling query_data as the alternative for large tabular data, though it does not contrast with other nearby siblings like datamesh_get_datasource_info.

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 context: use this for whole-datasource summarization, and switch to query_data with filters when a tabular datasource exceeds the inline size limit. No explicit "do not use when" clause for gridded/tabular edge cases, but the routing condition is clear.

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

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

Despite annotations already signaling a read-only, open-world operation, the description adds extensive behavioral detail: staging happens first, oversized results are refused with narrowing advice, tabular queries may be refused, limited results are flagged as previews, and variable resolution is reported via resolved_variables. None of this contradicts 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 most important constraints — small inline results, staging, size refusals, and preview warnings — are front-loaded. The description is long but largely earns its length for a 21-parameter tool, though some limit and resampling details duplicate the schema.

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

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

Given the complex schema, annotations, and available output schema, the description covers the critical operational behavior: sizing, refusal conditions, preview limitations, and variable resolution. It could be more complete by explicitly directing large-result use cases to export_query, but 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 description coverage is 100%, so the schema already documents all 21 parameters thoroughly, including limit and time_resolution interactions. The description adds meaningful semantics for CF standard_name variable resolution and preview behavior, but much of its parameter discussion repeats what is already in 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 — query a datasource and return small results inline — and clarifies the inline-size scope. It also mentions stage_query for sizing, but does not explicitly distinguish this tool's purpose from the sibling export_query, leaving some sibling selection ambiguity.

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

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

It gives clear operational context: use stage_query before calling, previews should not be used for statistics, and aggregate_operations or time_resolution should be used instead. It also explains when large results are refused, but it does not explicitly name export_query as the alternative for larger exports, leaving one key routing decision implicit.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond that: results are credential-scoped, and a datasource absent from results may simply be inaccessible rather than nonexistent—an important constraint for interpreting output.

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, purpose front-loaded, no wasted preamble. The second sentence is slightly redundant—'either does not exist or is not accessible with these credentials' largely restates 'do not report it as nonexistent'—but the constraint is worth stating once.

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 detail is unnecessary, and the description covers the key interpretive caveat for a search tool. It could go further by noting pagination/limit interaction or pointing to get_datasource_info for single-record lookups, 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 every parameter (bbox, limit, detail, search, time_start, time_end) is already documented in the schema. The description contributes no additional parameter 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 ('Search the Oceanum Datamesh catalog for datasets'), making the operation unambiguous. It does not, however, differentiate itself from siblings like datamesh_get_datasource_info; that routing distinction only appears in the schema's 'detail' parameter, not in the description.

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 accessibility caveat ('catalog search only covers datasources accessible to the credentials used for this request') is genuinely useful usage guidance. But the description never says when to prefer this tool over siblings such as get_datasource_info for a single dataset, or when a text/bbox/time filter is the right approach—usage is only implied.

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

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

Annotations declare readOnlyHint/openWorldHint, so the safety bar is already met; the description still earns credit by disclosing non-obvious behavior: no data is downloaded, limit+resampling makes the size an upper bound, and CF standard_name variables get resolved with resolved_variables echoed back. It omits cost/latency or rate-limit context for what is effectively a repeated exploratory call.

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 dry-run semantics, then caveats in descending priority; every sentence carries information. It is a bit long and partially restates the limit/time_resolution interaction already present in the limit parameter description, which is mild 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 21 parameters, an output schema, and annotations, the description covers what structured fields cannot: that nothing is downloaded, how the size verdict relates to query_data, and the upper-bound caveat. Nothing essential for correct invocation is missing, though staging cost and whether the echoed canonical query is reusable could be stated.

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

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

Schema coverage is 100%, so baseline is 3 and the schema already documents all 21 parameters. The description adds genuine meaning beyond it by specifying the CF standard_name resolution rule for variables and how the response echoes resolved names, a behavior not stated in the variables schema field.

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 pairing ("Dry-run a query: report the result size WITHOUT downloading any data") that immediately distinguishes it from siblings like datamesh_query_data and datamesh_export_query. An agent can tell exactly what this tool does 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?

It gives an explicit usage rule ("Always stage before retrieving data you have not sized") and routes the agent by naming query_data as the consumer of the size verdict. It does not explicitly cover the export path or state the inverse exclusion ("do not use this to fetch data"), so routing is clear 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=true, and openWorldHint=true. The description adds genuinely new behavioral context: only supplied fields are modified and the rest remain untouched, plus the read-only-mode availability gate. It does not explain what makes the operation destructive (e.g. overwriting existing field values), which is the one remaining gap.

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

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

Three short sentences, front-loaded with the core action, then the partial-update rule, then the availability gate. No filler and every sentence carries 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?

An output schema exists, so return values need not be described. For a mutation tool with full schema coverage and rich annotations, the description covers scope, partial-update semantics, and the read-only limitation. Only the destructive consequence is left implicit for the agent to infer.

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 seven parameters including datasource_id, info, name, tags, labels, details, and description are already documented with formats and length limits in the schema. The description adds nothing parameter-specific here, 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?

The description names a specific verb and resource ("Update metadata properties on an existing datasource"), which is unambiguous and clearly distinct from the read-oriented siblings (search_catalog, get_datasource_info, query_data). It stops short of naming any sibling, but since no other tool in the set performs updates, differentiation is implicit.

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

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

It gives a clear when-not condition ("Not available when the server runs with OCEANUM_MCP_READ_ONLY set") and clarifies the partial-update contract, so an agent knows changes are additive per-field. No alternative tool is named, but none exists in this family for metadata mutation.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about permanence, whether directories must be empty, permission requirements, or whether the operation can be undone. For a destructive delete tool with zero annotation coverage, this is a substantial 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?

A single efficient sentence with the resource front-loaded and no padding. It is well-sized, though its brevity is partly under-specification rather than tight information density.

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, but a destructive tool with no annotations and no description of irreversibility or failure modes leaves the agent without critical context for safe 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 100%, so both 'path' and 'recursive' are already documented in the schema. The description adds no syntax, format, or behavioral nuance beyond what the schema states, which is the baseline expectation 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 (delete) and resource (file or directory) scoped to Oceanum storage, which is enough to separate it from storage_write_file, storage_read_file, and storage_list_files. It does not explicitly name a sibling or contrast with one, so it falls short of the top score.

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 offers no guidance on when to use this tool versus alternatives, no prerequisites, and no mention that deletion is likely irreversible. The only usage-adjacent hint lives in the schema's 'recursive' field, not the description.

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

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

No annotations are provided, so the description carries the burden. 'Check if ... exists' strongly implies a side-effect-free boolean query, and the existence of an output schema means return format need not be explained. However, it says nothing explicit about read-only semantics, permissions, or behavior for non-existent/invalid paths.

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

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

A single tight sentence with the verb and scope front-loaded and zero wasted words. Nothing to trim and nothing important buried.

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

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

For a one-parameter existence check with a fully documented schema and an output schema covering the return value, the description is nearly sufficient. The only missing piece is any hint about path conventions or behavior for special cases.

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

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

Schema description coverage is 100% and there is a single required parameter, so baseline is 3. The description adds no extra meaning about path format (absolute vs relative, bucket prefixes, directory conventions) beyond what the schema 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?

The description states a specific verb+resource ('check if a file or directory exists') scoped to 'Oceanum storage', which is unambiguous and distinct from siblings like storage_read_file or storage_list_files. It doesn't explicitly name those siblings, 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?

There is no guidance on when to use this versus alternatives such as storage_file_info or storage_list_files, nor any note about prerequisites or typical contexts. The agent must infer usage entirely from the name.

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

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

No annotations are provided, so the description carries the full behavioral burden. It adds only that the target may be a file or a directory; it does not say whether a missing path errors or returns empty, whether it follows symlinks, or what permissions are required for Oceanum storage. For a bare read tool this leaves notable gaps.

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

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

A single front-loaded sentence with zero filler. The core verb and resource lead the sentence, and nothing is repeated from the title or restated redundantly.

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

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

The tool is simple: one required path parameter and an output schema that already documents the returned metadata fields, so the description need not explain return values. It is largely complete for such a low-complexity read operation, though it omits error behavior on nonexistent paths.

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

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

There is a single parameter with 100% schema description coverage ('Path to inspect.'), so the schema already documents it. The description adds no format examples, accepted path prefixes, or relative-vs-absolute semantics beyond what the schema provides, matching the baseline of 3 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+resource: 'Get metadata about a file or directory in Oceanum storage.' An agent can distinguish it from storage_read_file, storage_list_files and storage_write_file because it returns metadata rather than content or listings. It stops short of explicitly naming siblings or the info-only scope, so it is clear but not fully differentiated.

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

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

The description gives no when-to-use guidance: nothing says when to prefer this over storage_file_exists (existence check) or storage_list_files (enumerate a directory). Usage is only implied by the tool's name and purpose. No prerequisites, exclusions, or alternatives are mentioned.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'List' implies a read-only operation, but the description says nothing about permissions, authentication, non-recursive default behavior, or rate/pagination limits, leaving behavioral traits to inference.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though its brevity edges toward under-specification rather than maximal information density.

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

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

The tool is simple (two optional params) and has an output schema, so return values need not be described. However, with no annotations the agent gets no explicit confirmation of the read-only nature or permission requirements, leaving a small but real gap for an otherwise minimal definition.

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 'path' and 'recursive' are fully documented in the schema, making 3 the baseline. The description adds no syntax or format detail (e.g., what a recursive listing returns) beyond what the schema 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 states a specific verb ('List') and resource ('files and directories in Oceanum cloud storage'), which an agent can easily distinguish from sibling reads like storage_file_info or storage_read_file. It stops short of explicitly naming sibling alternatives, so it is clear but not differentiated at the highest level.

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 alternatives are named. The listing verb implies a browse/explore use case, but nothing tells the agent when to prefer this over storage_file_info or datamesh_search_catalog.

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

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

No annotations are provided, so the description carries the full burden; 'Read' implies a non-mutating operation, and the 'text file' qualifier usefully signals that binary content may be unsupported. However, it says nothing about missing-file behavior, permissions, encoding, or size limits, which are real risks for a file fetch.

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

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

A single tight sentence that front-loads the action and resource with zero filler. Correctly sized for a one-parameter tool.

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

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

The tool is simple, the sole parameter is documented in the schema, and an output schema exists so return values need not be described. Only error/edge-case behavior (missing file, binary content) is left unaddressed.

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

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

Only one parameter exists and schema description coverage is 100%, so the schema already documents 'path' fully. The description adds no path syntax, relative-vs-absolute, or format detail beyond what the schema provides, 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 (read) and resource (contents of a text file) scoped to Oceanum storage, which cleanly distinguishes it from write/delete/list siblings. It stops short of naming an alternative or explicitly contrasting with storage_list_files or storage_file_info.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no reference to alternatives such as storage_file_info (metadata) versus this tool (contents). Usage is only inferable from the 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?

No annotations are provided, so the description carries the full burden. It does disclose the most consequential behavior — silent overwrite of existing files — which is genuinely useful for data-loss avoidance. However it says nothing about required permissions, content encoding/type handling, size limits, or whether the write is atomic, leaving meaningful gaps for a mutation tool.

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

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

Two short sentences with zero filler. The core action is front-loaded and the create-or-overwrite caveat immediately follows, so nothing has to be hunted for.

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

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

An output schema exists, so return values need not be explained, and the schema fully covers both parameters. For a simple two-parameter write, the description covers the essential behavioral surprise (overwrite). Only minor gaps remain — no auth/permission note, which matters for a mutation tool with no annotations.

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

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

Schema description coverage is 100% and both parameters are documented there, so the baseline is 3. The description adds no syntax, path-format, or content-format detail beyond what 'path' and 'content' already convey in the schema.

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

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

States a specific verb and resource: 'Write text content to a file in Oceanum storage.' The verb contrasts naturally with siblings like storage_read_file and storage_delete_file, though it never names a sibling explicitly. An agent can identify the operation without opening the schema.

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

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

Usage is implied by the operation itself (write/overwrite a file), but there is no statement of when to prefer this over storage_delete_file or storage_file_exists, nor any prerequisite guidance. The 'creates if absent, overwrites if present' line does hint at idempotent upsert semantics, which is the closest thing to usage context.

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