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 is a mutation tool that never states required permissions, whether an existing AVU with the same attribute is overwritten or rejected, or any iRODS-specific constraints. Only the target taxonomy is conveyed.

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, and the purpose and valid targets come first. Efficient, though it sacrifices depth for brevity.

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

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

For a mutation tool with no annotations and no output schema, the description covers what is being created and where, and the schema fully documents parameters. However, it omits the behavioral context (permissions, overwrite semantics, auth) an agent needs 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%, so the schema already documents all five parameters including the enum for target_type and the unit default. The description adds no syntax or format detail beyond restating the target types, so 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?

States a specific verb ('Add') and resource ('AVU'), spells out the acronym, and enumerates the valid targets (file/data-object, directory/collection, resource, user). It is clearly the singular add operation, though it never explicitly distinguishes itself from the sibling ds_add_avus (batch) tool.

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

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

No when-to-use guidance is given. With siblings like ds_add_avus, ds_delete_avu, ds_list_avus, ds_search_files_by_avu, and the mesa_avu_* tools, the description should route the agent (e.g., single vs. bulk add), but it offers nothing.

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

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

With no annotations, the description carries the full burden. It usefully discloses a cross-system side effect — mirroring all AVUs into DuckLake as ONE snapshot — which is genuinely non-obvious from the schema. However, it omits critical behavior for a mutation tool: required permissions, what happens on partial failure (atomicity of the snapshot vs the AVU write), and duplicate-attribute handling.

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 that conveys batch semantics, the mirroring side effect, and the efficiency motivation with no filler. Nothing could be trimmed without losing 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?

There is no output schema or annotation coverage, so the description must stand alone. It covers purpose and the dual-write behavior but leaves return values, error/partial-failure semantics, and duplicate handling unspecified — adequate for the happy path, thin for a two-system mutation.

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

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

Schema description coverage is 67%, so most parameters are documented in the schema itself (target as an iRODS path, avus as batched AVUs). The description adds only the detail that target may be a data-object or collection, and says nothing about the unit field or target_type beyond defaults. Baseline 3 is appropriate given the schema does most of the work.

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

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

The description names a specific verb (add), resource (AVUs), and scope (MULTIPLE AVUs to one data-object/collection in a single call), which clearly sets it apart from the singular ds_add_avu sibling by emphasizing the batched nature. It stops short of naming the sibling, so the differentiation is inferential rather than explicit.

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

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

'efficient bulk tagging' implies when this tool is preferable (large AVU sets, single snapshot), but there is no explicit when-to-use/when-not guidance and no pointer to ds_add_avu for single-AVU cases. Usage 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?

No annotations are provided, so the description carries the full burden. It does not disclose overwrite behavior, permission requirements, recursive copy semantics beyond the schema, error behavior, or return values; 'new location' is the only behavioral hint.

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 sentence, front-loaded with the verb and core resource. There is no filler or redundancy; the description is appropriately sized for a simple two-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 schema fully covers both parameters and constraints, so the agent can call the tool correctly. However, with no annotations or output schema, the description is thin on behavioral context such as permissions, overwrite edge cases, and return behavior.

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 source_path and destination_path are fully documented in the schema, including directory recursion and the requirement that the destination not already exist. The description adds no parameter-level meaning beyond what the schema already provides.

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 ('Copy') and resource ('file (data-object) or directory (collection)') to a new location. It does not explicitly differentiate from the sibling ds_move_file, but an agent can infer the distinction.

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

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

No when-to-use or when-not-to-use guidance is provided. It does not mention alternatives such as ds_move_file, prerequisites, or conditions where copying is preferred over moving or writing.

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 load; it does add real behavioral context by disclosing the return content (ticket string plus applied restrictions) and an authorization constraint (anonymous users may not create tickets). It stops short of describing persistence/lifecycle implications of creating a ticket or any rate limits.

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

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

Two short sentences, front-loaded with the core action and followed by the return value and precondition. No filler or restatement of the title.

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

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

For a seven-parameter creation tool with no output schema, the description covers purpose, return content, and one key precondition, and the schema fully documents parameters. It could go slightly further on permission requirements or ticket lifecycle, but nothing essential to a correct call is missing.

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

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

Schema description coverage is 100% with all seven parameters documented (mode enum, expiry, uses_allowed, host/user restrictions, write_byte_limit), so the schema already does the heavy lifting. The description only echoes the read/write mode distinction and adds no syntax or interaction guidance 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 (create) and resource (iRODS ticket) plus scope (data object or collection) and the access-mode dimension. It is clearly distinguishable from siblings like ds_modify_ticket and ds_delete_ticket by its creation semantics, though it never names those 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?

Usage is implied by the name and the 'read or write' framing, and one precondition is given ('Anonymous users may not create tickets'). However there is no explicit guidance on when to use this versus ds_modify_ticket or ds_use_ticket, and no note on required permissions for non-anonymous users.

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 says 'delete' but does not state that this is destructive/irreversible, whether it requires specific permissions, whether it is idempotent, or what happens if the AVU does not exist.

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

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

A single front-loaded sentence with no filler; the verb and target scope come first. Nothing is padded or repeated from structured fields.

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 mutation with six parameters, no annotations, and no output schema, the description is too thin. It omits permission requirements, error/failure behavior, and the id-vs-attribute selection rule, leaving behavioral gaps the structured fields do not cover.

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 six parameters, making 3 the baseline. The description adds no extra parameter meaning, and notably does not clarify the interaction the schema hints at (attribute can be ignored if id is supplied).

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 (AVU) plus the full set of target scopes (file, directory, resource, or user). An agent can distinguish it from siblings ds_add_avu and ds_list_avus purely by the verb without opening a schema.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives or follow-up tools (e.g. ds_list_avus to confirm what exists before deleting). Usage is only implied by 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 doesn't state whether deletion is recursive for directories, whether it's reversible, what permissions are required, or what happens to nonexistent paths. These are critical for a destructive operation.

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

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

Single sentence with no wasted words, front-loading the action and resource.

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 operation with no annotations and no output schema, the description is too sparse. It should at least mention whether directory deletion is recursive, what happens on failure, or any side effects.

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 the single parameter. The description adds only a minor clarification that the path can point to a file or directory, which is already implied by the parameter description. 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?

States a specific verb (delete) and resource, and clarifies that 'file' means data-object and 'directory' means collection. This distinguishes it clearly from siblings like ds_delete_avu or ds_delete_ticket. However, it doesn't differentiate further about scope or behavior relative to those 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?

No guidance on when to use this tool versus alternatives, nor any prerequisites (e.g., permissions, whether the path must exist). The description is purely definitional.

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

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

With no annotations, the description carries the full burden and does well: it discloses that authorization is server-enforced (issuer/admin) and that anonymous callers are rejected at the tool layer, which tells the agent about both permission needs and failure behavior. It stops short of saying whether revocation is reversible or what happens to already-issued tickets, leaving some behavioral 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?

Three short sentences, front-loaded with the action, then the authorization constraint and the rejection behavior. No filler and nothing 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?

For a single-parameter, no-output-schema, no-annotation tool, the description covers purpose, the authorization model, and caller rejection. It is largely complete, though a note on reversibility or behavior for expired/already-used tickets would close the remaining gap.

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

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

Schema description coverage is 100% for the single required 'ticket' parameter, so the schema already defines it as the ticket string to delete. The description adds no syntax, format, or sourcing detail beyond that, matching the baseline 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 (Revoke) and resource (an existing iRODS ticket), which cleanly distinguishes it from the sibling create/modify/use/list ticket tools. An agent can identify this as the deletion counterpart 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 supplies preconditions (issuer or admin only; anonymous callers rejected), which is useful usage context, but it never states when to choose this over alternatives like ds_modify_ticket or when a ticket should be revoked rather than left to expire. Usage is implied rather than routed.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the return format (JSON) and the scope of results (all entries under the given collection), which is genuinely useful, but says nothing about permissions required, result ordering, size limits, or error behavior on a bad path.

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?

Four short sentences, front-loaded with the core purpose and with no filler. Slight redundancy between 'The output is in JSON format' and 'The output contains all entries...', but it is tight overall.

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

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

There is no output schema, so the description is the only source on return values; it partially covers this (JSON, all entries under the collection). It omits behavior for nonexistent paths, permission requirements, and whether depth truncation is signalled, leaving gaps for a tool that returns unbounded recursive data.

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

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

Schema description coverage is 100%, with 'depth' fully documented including default 3, minimum 1, and maximum 10, so the baseline is 3. The description adds only that the path must be an iRODS path, which is a marginal semantic addition over the schema's 'path to the directory (collection) to list'.

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

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

States a specific verb ('Get') and resource ('recursive tree view of files and directories'), and maps iRODS vocabulary (data-objects/collections) to the generic terms. It does not, however, distinguish itself from the closely-named siblings ds_list_directory and ds_list_directory_details, which an agent must disambiguate on its own.

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 only guidance is a prerequisite: 'The specified path must be an iRODS path.' There is no statement of when to prefer this recursive tree over the flat listings (ds_list_directory, ds_list_directory_details) or search tools, and no exclusion conditions.

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

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

With no annotations, the description carries the full burden. It usefully discloses a non-obvious behavioral trait: this tool returns instructions for downloading via WebDAV, GoCommands, and iCommands rather than the file content itself, which prevents an agent from expecting bytes. It says nothing about permissions, existence checks, or error behavior for an operation that must touch a remote iRODS path.

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 behavior. The second sentence ('The specified path must be an iRODS path') is largely redundant with the first, and there is a typo ('contgent'), keeping it out of the top band.

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

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

For a two-parameter tool with no output schema and no annotations, the description adequately explains what comes back (per-tool download recipes) and the input constraint. It is thin on failure modes and permission requirements, but nothing essential for invoking it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description only restates that the path must be an iRODS path and never addresses local_path (the required full path with file name), so it adds essentially nothing beyond the schema — the baseline 3.

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

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

States a specific resource (a file/data-object at an iRODS path) and an unusual but precise output: download instructions rather than file bytes. It does not name the sibling it must be distinguished from (ds_read_file, which returns content), so it stops short of a 5.

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

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

Usage is implied by the constraint that the path must be an iRODS path and by the fact that it returns recipes rather than data, but there is no explicit when-to-use/when-not guidance and no mention of ds_read_file or ds_upload_file as alternatives.

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

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

With no annotations, the description carries the full burden. It usefully discloses the return shape (dict of output parameters, plus stdout/stderr when 'ruleExecOut' is requested) and a pre-execution access check on path-typed parameters. It omits the most consequential trait: that executing a rule (especially arbitrary inline iRL) can mutate or delete data, and no side-effect or failure behavior is described.

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

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

Three sentences, front-loaded with the core action, then modes, then return behavior, then the safety check. No filler and nothing restated from the title or schema verbatim.

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 5-parameter tool with a nested free-form object, no output schema, and no annotations, the description covers invocation modes, return format, and one permission gate. It is short of complete because side effects/destructiveness and error behavior for rule execution are not addressed.

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 adds real meaning: the rule_name/rule_text duality, the semantics of output_parameters via 'ruleExecOut', and the check applied to path-typed inputs. Only instance_name and input_parameters binding behavior remain unelaborated.

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?

"Run an iRODS rule" gives a specific verb and resource, and the two invocation modes (server-installed rule_name vs inline rule_text) sharpen it. It does not name siblings like ds_list_rules or ds_get_rule_definition to differentiate scope, 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?

"Supply either rule_name (server-installed) or rule_text (inline iRL)" gives in-tool parameter routing, and the schema reinforces the exactly-one constraint. However, there is no guidance on when to use this tool versus a wrapper or a more specific sibling, and no prerequisites are 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?

No annotations are supplied, so the description carries the full behavioral burden. It does not state that this is a read-only retrieval, does not disclose whether access permissions or tickets are required, and says nothing about what the returned metadata contains. 'Detailed metadata' is left undefined.

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

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

A single front-loaded sentence with no filler; the action and target come first. It is efficient, though arguably too terse to earn a top score given the missing routing and behavior 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?

For a simple one-parameter read tool with no output schema, the description is minimally adequate but omits the two things an agent would want: what constitutes 'detailed metadata' and how this differs from ds_get_metadata. With no annotations and no output schema, more context was warranted.

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

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

Schema description coverage is 100%, and the single 'path' parameter is fully documented in the schema, including the data-object/collection mapping. The description adds nothing beyond the schema, so the baseline of 3 applies.

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

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

The verb 'Retrieve' plus the resource 'detailed metadata about a file or directory' clearly states what the tool returns, and it even names the two entity types it handles (file/directory). It does not, however, distinguish itself from the similarly named sibling ds_get_metadata or from ds_list_directory_details, leaving the agent to infer the boundary.

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

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

There is no statement of when this tool should be used rather than ds_get_metadata, ds_read_file, or ds_list_directory_details, and no prerequisites or exclusions. The agent gets a purpose but no routing guidance.

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

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

No annotations are provided, so the description must carry the behavioral burden. It discloses that it returns a 'resolved target type' and 'AVU list', which is useful, but does not cover permissions, side effects, error cases, or whether metadata is inherited.

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

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

Two sentences, front-loaded with the action and resource, and the second sentence adds return-shape context. No wasted words.

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

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

For a single-parameter read tool with no annotations and no output schema, the description gives a reasonable summary but lacks details about return format, pagination, permissions, or behavior on missing paths. It is minimally adequate but could do more.

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 only one parameter, so the baseline is 4. The description reinforces the path semantics ('iRODS path data object or collection') without adding new format details beyond the schema.

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

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

The description states a specific verb and resource: 'Fetch the full AVU metadata bundle for an iRODS path (data object or collection).' It clearly distinguishes itself from siblings like ds_list_avus (list only) by promising the full AVU bundle and resolved target type.

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

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

It implies use when you need metadata for a single iRODS path but does not explicitly state when to use this over ds_list_avus or ds_search_metadata. There are no exclusion conditions or alternative recommendations.

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

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

With no annotations, the description carries the full behavioral burden, and it does so well for the critical trait: it discloses that iRODS does not expose PCF config through PRC and that this is a stub returning config=None plus a note. It omits auth/permission or failure-mode details, but the stub disclosure is the key fact.

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, zero waste, front-loaded with the purpose and immediately followed by the limitation. Nothing to trim.

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?

There is no output schema, but the description compensates by describing the return shape (config=None and a note). Combined with the fully documented single parameter, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100% and the single parameter is documented as 'Name of the PCF policy to introspect.' The description's 'named ... policy' phrasing adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Return the configuration of a named Policy Composition Framework policy.' An agent can tell this is a config-introspection tool rather than a policy lister. It does not explicitly name ds_list_policies as the related sibling, so it falls short of a 5.

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

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

Usage is implied by the name and by the note that this is a stub, which signals the agent should not expect real config data. However, no explicit when-to-use guidance or named alternative (e.g., ds_list_policies) is given.

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

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

With no annotations, the description carries the full burden and discloses the critical failure mode: the tool is best-effort and usually returns None for 'definition'. It does not state read-only status, authentication requirements, or behavior when the rule name is not found, but the key behavioral limitation is clearly surfaced.

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

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

Two tight sentences: the purpose is front-loaded and the important limitation follows immediately. Every clause earns its place with no redundant or vague wording.

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, annotation-free, output-schema-free tool, the description covers purpose, return field, and the dominant failure mode. It still omits error behavior (e.g., nonexistent rule) and read-only/authorization context, but the essential calling information 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?

Schema coverage is 100%, so the single 'name' parameter is already documented in the schema. The description only restates that it accepts a named iRODS rule and does not add syntax, format, or lookup semantics beyond what the schema provides.

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

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

States a specific verb and resource: 'Return the source of a named iRODS rule.' This clearly distinguishes it from ds_list_rules (which lists rules) and ds_execute_rule (which runs them), but it does not explicitly name or route against those 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 a strong contextual caveat: iRODS does not expose rule sources through PRC, so this is best-effort and the 'definition' field is None on most servers. That warns the agent not to rely on it, but it offers no explicit when-to-use or alternative-tool guidance.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that output is JSON and gives example fields (ID, expiration time), plus an auth restriction for anonymous users. It does not mention error behavior, permissions beyond anonymous, or other operational traits.

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, zero waste, and the core purpose is front-loaded. The auth constraint follows naturally without burying the main action.

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 one-parameter read tool with no output schema, the description covers the essential purpose, auth requirement, and return format. It is nearly complete, though it could briefly note error conditions or whether the response includes all ticket fields.

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%: the single parameter 'name' is fully documented in the input schema. The description adds no syntax or format details beyond referring to 'a specific iRODS ticket', so the baseline of 3 applies.

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

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

The description states a specific verb ('Get information about') and resource ('a specific iRODS ticket'), and adds the return format ('JSON'). It distinguishes from the sibling ds_list_tickets by specifying 'specific', but does not explicitly name that alternative.

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 includes an auth prerequisite ('Anonymous users are not allowed to get ticket information'), which gives context. However, it provides no explicit when-to-use versus alternatives, nor any exclusions beyond the anonymous restriction. Usage is only implied by the purpose.

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 does disclose the return shape's content ('API names that can be requested to each directory'), which is genuinely useful context, but it omits any statement about read-only semantics, side effects, permissions required, or the fact that access is scoped by server policy.

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

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

Two short sentences with no filler, and the core purpose is front-loaded. The second sentence is slightly awkwardly phrased ('API names that can be requested to each directory') but still earns its place by describing output 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?

For a simple zero-arg discovery tool with no output schema, the description covers the return shape adequately, but it should at minimum clarify the read-only nature and how it relates to the other directory-listing siblings. No output schema exists, so explaining what comes back is valuable and partly done.

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

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

The tool takes zero parameters and the schema confirms this ('No inputs'), so there is no parameter semantics for the description to add. Baseline 4 applies for a zero-argument tool.

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

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

States a specific verb and resource ('Get a list of directories (collections)') and adds scope ('that this server is allowed to access'), which distinguishes it from a generic directory listing. However, it never differentiates itself from close siblings like ds_list_directory, ds_list_directory_details, or ds_directory_tree, leaving the agent to guess which listing tool applies.

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

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

No when-to-use guidance, no prerequisites, and no mention of the sibling listing tools. An agent cannot tell from this text whether this is a discovery/bootstrap call or an alternative to ds_list_directory.

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

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

With no annotations, the description carries the full behavioral burden, and it discloses almost nothing beyond the target kinds. It does not say whether this is a read-only operation, what permissions are required, what the result shape is, or how empty results are handled.

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

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

A single front-loaded sentence with no filler; the verb and resource lead, and the target list follows immediately.

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

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

For a two-parameter read tool with no output schema and no annotations, the description is adequate on inputs but silent on return values and safety profile. It covers the minimum but leaves the agent guessing about result shape.

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 both parameters and the enum. The description adds mild value by mapping 'file (data-object)' and 'directory (collection)' onto the single 'path' target_type, clarifying that path covers both cases, but adds no syntax or format detail.

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

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

The description states a specific verb and resource ('List AVUs') and enumerates the four kinds of targets it operates on. It distinguishes itself from the add/delete AVU siblings by naming the read direction, though it doesn't explicitly contrast with siblings like ds_get_metadata that may also surface AVUs.

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 says what the tool lists but gives no when-to-use guidance, no prerequisites, and no alternatives. An agent choosing between ds_list_avus, ds_get_metadata, and ds_search_files_by_avu gets no routing help from this 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?

With no annotations, the description carries the full burden. It discloses the output format (JSON) and that entries correspond to the given collection, which is useful. It omits behavioral facts a caller would want: that it is a read-only operation, whether permissions or existence checks apply, and how errors are surfaced.

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?

Four sentences, and the middle two are largely redundant — the path/format statement and 'the output contains entries in the given directory path' restate what the opening sentence already conveyed. It is not bloated, but it is not tightly front-loaded either.

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 annotations and no output schema, the description must stand on its own for a 3-parameter listing tool. It covers the essentials (what is listed, format, pagination) but leaves sibling differentiation and error/permission behavior unaddressed, which is a meaningful gap given several near-identical listing tools in the family.

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 path, limit and offset are already fully documented in the schema; the baseline is 3. The description repeats the pagination intent of limit/offset without adding syntax, defaults or constraints beyond what the schema already provides.

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

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

States a specific verb (Get/list) and resource (files/data-objects and directories/collections in a path) and clarifies the iRODS path requirement. However, it does not distinguish itself from closely named siblings such as ds_list_directory_details or ds_directory_tree, which a caller could easily confuse it with.

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 partial usage guidance — the path must be an iRODS path and offset/limit should be used to paginate large directories. It never states when to choose this tool over ds_list_directory_details or ds_directory_tree, so the routing decision is left 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?

With no annotations and no output schema, the description carries the full burden and does reasonably well: it states that output is JSON, that entries include access lists for users/groups, and that files carry replica information. What is missing is any statement about permissions/auth needed to read a path or error behavior on invalid iRODS 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?

The core operation is front-loaded in the first sentence, and the remaining sentences carry distinct payload (path type, output format, output contents, pagination). It is slightly repetitive in restating 'files (data-objects)' multiple times but not wasteful enough to drop below 4.

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 annotations and no output schema, the description covers the essentials an agent needs: required path semantics, JSON output, what each entry contains, and how to page through large results. The notable hole is the absence of any routing guidance relative to ds_list_directory.

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 path, limit, and offset are already fully documented with defaults and max values. The description only restates the pagination intent, adding no syntax or format detail beyond the schema, which matches the baseline 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?

The description names a specific verb (Get/list) and resources (files/data-objects and directories/collections) plus the scope ('full detailed info'), and it clarifies the iRODS-specific terminology mapping. It does not differentiate itself from the sibling ds_list_directory, which is the obvious alternative, 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?

The only usage guidance is the pagination hint ('Use offset and limit parameters to paginate through large directories'), which is really parameter guidance. Nothing tells the agent when to choose this tool over ds_list_directory or ds_directory_tree, nor are there prerequisites or exclusions.

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

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

With no annotations, the description carries the full load, and it discloses a genuinely important behavioral fact: the server-side PCF envelope is always included, and iRODS does not expose PCF state through PRC, so that portion is 'a documented stub.' That warning usefully tells the agent to distrust part of the output. It omits permission/auth requirements, which is the 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?

Front-loads the core action ('List policies...') and then layers the return-shape and stub caveats. Dense with backticked identifiers but every sentence contributes; only minor tightening is possible.

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 or annotations, the description does the work of explaining what comes back (policy AVUs plus an always-present PCF envelope that is a stub). It does not describe the AVU record shape or required permissions, but for a single-parameter read tool it is largely complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by identifying what the param selects (the single project root whose mesa.policy.* AVUs are returned) and framing those as 'the policies mesa-mcp itself honours,' which clarifies relevance beyond the field's own 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 specific verb and resource ('List policies in effect for the Data Store') and clarifies what is returned (MESA policy AVUs prefixed mesa.policy.* alongside the PCF envelope). It implicitly separates itself from generic siblings like ds_list_avus by scoping to policy AVUs, though it never names an alternative explicitly.

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

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

'With project_path, returns...' implies a conditional usage (supply the path to get project-scoped policies), and the schema notes omitting it returns only the envelope. But it never states when to prefer this over ds_get_policy_config or ds_list_avus, so guidance is implied rather than explicit.

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

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

With no annotations, the description carries the full burden, and it does disclose genuinely useful behavior: the result is a best-effort list of delayed rules only, the static rule base is not exposed by PRC, and the 'note' field documents that limitation. That is real context about result completeness. It still omits permissions needed and whether results are paginated or ordered.

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 with no filler. The core action is front-loaded, and the second sentence carries the one piece of caveat information the caller actually needs. Every clause earns its place.

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

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

For a zero-argument, read-only listing tool with no annotations and no output schema, the description covers purpose, scope, and the key limitation on returned data. Only minor gaps remain (permissions, ordering, how to read the 'note' field in practice).

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

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

The tool takes zero parameters, so the schema is complete by definition and there is nothing for the description to disambiguate. Baseline 4 applies for a no-argument tool.

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

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

States a specific verb and resource: 'List iRODS rules visible to the caller'. This clearly separates it from ds_get_rule_definition (single rule), ds_execute_rule (run a rule), and ds_list_policies (policies, not rules). It does not 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?

'List ... visible to the caller' implies enumeration and caller scoping, which is enough to infer when to reach for it. However, it never states when to prefer this over ds_get_rule_definition or ds_list_policies, and gives no prerequisites or exclusions. Usage is implied rather than guided.

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 does disclose an access constraint (anonymous users rejected) and the return payload shape, which is useful. It omits pagination, ordering, and behavior on an empty ticket set, which are gaps for an unannotated 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?

Three short sentences, front-loaded with the action and payload, with the access restriction last. No filler, though the three sentences could be tightened into two.

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 supplies the return content (IDs, expiration times, JSON) and the auth gate. For a zero-argument list tool this is nearly complete; only pagination/ordering behavior is 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?

The tool takes zero parameters and both schema and description agree there are none; that is the baseline 4 case. No parameter semantics need explaining.

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

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

States a specific verb and resource ('Get a list of iRODS tickets') and summarizes the payload (IDs, expiration times, JSON). It distinguishes itself implicitly from ds_get_ticket_info and ds_create_ticket by being the enumeration call, though it never names those 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?

Usage is only implied: 'list' signals enumeration, and the auth prerequisite ('Anonymous users are not allowed to list tickets') tells the agent when it cannot call this. It never states when to prefer this over ds_get_ticket_info for a single ticket.

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, and it says nothing about what happens if the directory already exists, whether parent paths are auto-created, whether this is idempotent, or what permissions are required. For a mutation tool with zero annotation coverage these are significant omissions.

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

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

A single short sentence with no filler, and the core action is front-loaded. It is efficient, though its brevity shades into under-specification rather than pure tightness.

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 low-complexity with one fully documented parameter and no output schema, so little is strictly required. However, as a mutation with no annotations, the description should at minimum cover error/overwrite behavior or path semantics, and it covers neither.

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

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

Schema description coverage is 100% and the single 'path' parameter is documented as 'The path to the new directory to create.' The description adds no syntax, format, or relative-vs-absolute guidance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Make a new directory') and adds the domain synonym '(collection)' so an agent can map it to CDE terminology. It is clearly distinguishable from siblings like ds_list_directory, ds_move_file, or ds_delete_file. It stops short of explicitly contrasting itself with any sibling, so it is a solid 4 rather than 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 tool versus alternatives, no prerequisites, and no exclusions. It never mentions, for example, that ds_upload_file or ds_copy_file may create directories implicitly, nor what to do if the path already exists. Only the implied usage of the name is available.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states that access is modified but does not mention required permissions (e.g., must be owner or admin), whether the access level replaces or adds to existing permissions, what happens to existing access, or any side effects or error conditions for this mutation operation.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core action and targets 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 mutation tool with no annotations, no output schema, and four parameters, the description is too sparse. It omits critical context such as required permissions, behavioral effects (replace vs. add access), and usage guidance, leaving significant gaps for an agent to 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 already fully documents all four parameters including access levels, recursion, path, and user/group format. The description adds no additional meaning beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description states a specific verb ('Modify') and resource ('data access') plus the targets ('a user or group to a file (data-object) or directory (collection)'). It clearly identifies what the tool does, though it does not explicitly distinguish itself from the sibling tool ds_modify_access_inheritance, which also deals with access-related modifications.

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

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

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, no conditions for use, and no exclusions. It simply states the operation without any contextual usage information.

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. It says 'modify' but does not explain permission requirements, whether existing inherited access is recalculated, or the effect on already-existing child entries.

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 verb and resource front-loaded and no wasted words. It is terse rather than padded, though the brevity borders on under-specification.

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

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

For a mutation tool with no annotations and no output schema, the description is too thin: it omits permission needs, reversibility, and the recursive side effects that the 'recurse' parameter implies. Note also a mismatch — the description says 'file or directory' while the schema constrains 'path' to a directory (collection).

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 path, inherit, and recurse are fully documented in the schema itself. The description adds no parameter-level meaning beyond what the schema already provides, which is the expected baseline.

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

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

States a specific verb ('Modify') and resource ('data access inheritance flag') with clear scope ('file or directory'). It is understandable in isolation, but does not differentiate itself from the sibling ds_modify_access, which an agent must choose between.

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

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

No indication of when to use this versus ds_modify_access, no prerequisites, and no exclusions. Usage is only implied by the verb 'modify'.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that this is a mutation, that mode is immutable, that anonymous access is denied, and that applied restrictions are returned. It still omits important update semantics, such as whether omitted restrictions are cleared or preserved and what authorization beyond anonymous denial is required.

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

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

The description is four short sentences, front-loads the core action, and immediately states the key immutable constraint. Every sentence contributes useful information with no repetition or 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?

Given a mutation tool with no annotations and no output schema, the description supplies the essential return behavior, the immutable mode constraint, and an auth restriction. It is nearly complete, though it could say more about partial-update behavior and permission requirements beyond anonymous denial.

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 six parameters are already documented in the input schema. The description adds no parameter-level detail beyond the general notion of restrictions and the explicit exclusion of mode, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: modify restrictions on an existing iRODS ticket. It also clarifies the immutable scope (mode cannot be changed), which helps separate it from creation or deletion tools. It does not name sibling alternatives, so it falls short of a 5.

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

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

It implies usage for existing tickets and gives one concrete precondition: anonymous users are not allowed. However, it does not explain when to choose this over siblings such as ds_create_ticket, ds_delete_ticket, or ds_use_ticket, leaving routing to inference.

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

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

No annotations are provided, so the description carries the full disclosure burden. It never states that the source path is removed (destructive implication), what permissions are required, whether the operation is atomic, or how conflicts at the destination are handled — all critical 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?

A single tight sentence with the verb front-loaded and no filler. It is appropriately sized, though its brevity is partly the source of the behavioral gaps.

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

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

For a mutation tool with no annotations and no output schema, the description should at minimum note that the source is removed and that the destination must not exist. It omits both, leaving the agent without the destructive semantics it needs.

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%, with both old_path and new_path fully documented, including that new_path must not already exist. The description adds nothing beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (move) and both resource types (file/data-object, directory/collection), which is clear enough for an agent to act on. It does not explicitly distinguish itself from the sibling ds_copy_file, 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?

No guidance on when to use this versus ds_copy_file or ds_upload_file, no prerequisites, and no mention of what happens when the destination already exists beyond the schema note. The agent must infer usage entirely.

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

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

No annotations are provided, so the description carries the burden, and it does disclose meaningful behavior: the message is echoed, 'ok' is the fallback, the version is returned, and no iRODS session/credentials are needed. It is not exhaustive (no latency/timeout caveats), but for a stateless ping this is solid disclosure.

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 purpose, then behavior, then the constraint. Every sentence carries information; nothing is redundant.

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

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

An output schema exists, so return values need not be detailed, yet the description still summarizes them (echoed message + version). For a zero-required-parameter liveness tool, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 0% and the single 'message' property has no schema description, so the description must compensate. It does: it explains that the supplied message is echoed and that 'ok' is used when it is omitted, which resolves the nullable default.

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: a liveness/smoke check that echoes a message and the running mesa-mcp version. This is clearly distinguishable from every sibling, which all perform iRODS/data operations, and the 'no iRODS access required' clause reinforces the distinction.

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 'Liveness check' framing plus 'No iRODS access required' gives a clear condition for use: call it to verify the server is reachable when no data access is needed. It stops short of explicitly naming when not to use it or contrasting with an alternative, but no sibling overlaps this role.

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' plus 'partial content' reasonably conveys a non-destructive, bounded read, and the WebDAV note hints at inline-size limits, but the description never says what happens when the requested length is exceeded (silent truncation vs. error) or what permissions are needed on the iRODS path.

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, with no filler. The third sentence is a somewhat tangential fallback hint rather than core semantics, keeping it just under a 5.

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

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

With no output schema, the description should explain the return shape (raw content string, truncation indicator, encoding), and it does not. For a 3-parameter read tool with a size-limited payload, the omission of truncation/return semantics is the main gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does add one genuinely useful fact beyond the schema: that 'path' must be an iRODS path. It says nothing about 'length' or 'offset' beyond the schema's own text, so it stays at baseline.

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

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

States a specific verb and resource ('Read the partial content of a file (data-object)') and adds the offset-based partial-read scope, which separates it from a full-file tool like ds_download_file. It does not, however, explicitly name or contrast itself with the closest siblings (ds_get_file_info, ds_download_file, ds_read_file-adjacent 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?

The line 'If the file is too large to be displayed inline, use the WebDAV URI to access it' gives a conditional fallback, but the fallback is an external URI rather than a sibling tool, and there is no guidance on when to prefer this over ds_download_file or ds_get_file_info. Usage 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?

No annotations exist, so the description must carry the full behavioral burden. It discloses that the search is recursive and that matches come back as JSON, but says nothing about permissions, result limits, pagination, or performance on large trees — real gaps for a recursive search 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?

Three sentences, front-loaded with the core action before the constraints and return format. No filler, though the wildcard example duplicates the schema and could be trimmed.

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

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

For a single-parameter, read-only search tool with no annotations and no output schema, the description covers purpose, path constraint, pattern syntax, and return format. Missing operational details (permissions, result caps/pagination) keep it from being fully complete.

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

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

Only one parameter, and schema description coverage is 100%, so the schema already documents the wildcard behavior. The description's one genuine addition is that the path 'must be an iRODS path' and that the root is a search root rather than a file, but otherwise it largely repeats the schema.

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

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

States a specific verb (search) and resource (files/data-objects, directories/collections) and nicely glosses the iRODS terminology. It differentiates implicitly by 'matching a pattern' versus the sibling ds_search_files_by_avu, but never names that sibling or any alternative.

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 practical usage detail (root path must be an iRODS path; use '?' and '*' wildcards), which implies the intended use. However there is no explicit when-to-use/when-not guidance and no mention of alternatives like ds_search_files_by_avu or ds_list_directory.

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 states that results come back in JSON, but says nothing about whether AVU matching is exact or wildcard, whether permission filtering applies, result limits/pagination, or what an empty result looks like. For an unannotated search tool this is a notable gap.

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

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

Two tight sentences with the core action front-loaded and the return format appended. Nothing is padded, though the parenthetical glossary adds only mild value.

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

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

For a two-parameter read-only search with no output schema and no annotations, the description covers the essentials but omits matching semantics, scoping/limits, and result behavior. It is minimally viable rather than complete.

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

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

Schema description coverage is 100% for the two required parameters (attribute, value), so the schema already documents them. The description restates that search uses 'specified attribute and value' but adds no semantics beyond the schema, such as matching behavior or case sensitivity; 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 gives a specific verb (Search), resource (files/data-objects and directories/collections), and mechanism (iRODS AVU attribute-value matching). It clearly tells the agent what is searched and on what basis, though it does not explicitly distinguish itself from sibling search tools like ds_search_files or ds_search_metadata.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as ds_search_files, ds_search_metadata, or ds_list_avus. The agent must infer that this tool applies only when it already has an attribute-value pair, which is implied but never stated.

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

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

No annotations exist, so the description carries the full behavioral burden. It usefully discloses the permissive matching semantics and that result scope is selectable (data objects, collections, both), but says nothing about pagination, result volume, ordering, or any permission requirements — meaningful gaps for an unannotated search 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 tight sentences with no filler; the core verb+resource leads and the sibling comparison follows immediately. Every clause carries information.

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

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

For a four-parameter, fully schema-documented read tool with no output schema, the description covers matching semantics and result scoping adequately. It omits result volume/pagination behavior, which is the only notable gap given the absence of annotations.

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

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

Schema description coverage is 100%, so each of the four parameters is already documented, including the enum for target. The description reinforces that parameters are combinable and all optional, but adds no format, syntax, or CURIE-handling detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (search iRODS by AVU attribute/value/unit) and explicitly names the sibling it differs from, ds_search_files_by_avu. An agent can distinguish it from ds_search_files and ds_list_avus without opening a schema.

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

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

It draws an explicit contrast with ds_search_files_by_avu and explains the permissiveness (any combination of attribute, value, unit), which effectively tells the agent when this tool is the right choice. It stops short of stating the inverse condition — when to prefer the stricter sibling — so it is clear context rather than a full when/when-not 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?

With no annotations provided, the description carries the full burden, and it does disclose the critical trait that it returns instructions (not a performed upload) and enumerates three protocols (WebDAV, gocmd, iCommands). It stops short of stating permissions/auth needs, whether anything is actually written, or the output format.

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 repeats 'Returns how to upload' twice, which is redundant, and contains a typo ('contgent'). It is short and front-loaded, but the repetition and error cost it a point.

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 annotations and no output schema, the description must stand alone; it conveys the purpose and the key return type but omits auth/permission requirements and any detail on how the returned instructions are structured, leaving a modest gap for a tool an agent might otherwise mistake for a real upload.

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

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

Schema description coverage is 100%, so all three parameters (local_path, irods_path, is_dir) are already documented in the schema. The description only reinforces that the path must be an iRODS path, adding minimal meaning beyond the structured fields — 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 verb+resource (returns instructions for uploading a file/data-object to an iRODS path) and importantly clarifies the surprising behavior implied by the name 'upload_file' — it returns how to upload rather than performing the upload. It does not, however, differentiate itself from sibling write/upload paths such as ds_write_file.

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 and no alternatives named. The only constraint given is that the path must be an iRODS path; the agent is left to infer when this guidance tool is preferable to ds_write_file or ds_download_file.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses session scoping ('same caller'), the forward-looking effect on subsequent operations, that AVU writes get a via_ticket value in DuckLake, and that other callers are unaffected. It omits error/expiry behavior for invalid tickets and whether the ticket can be cleared, so not fully complete.

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

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

A single, front-loaded sentence with no filler; the core action and its scoping consequence lead, and the side-effect detail follows. Every clause earns its place.

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

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

For a session-state mutation tool with no annotations and no output schema, the description covers scope, side effects, and non-interference with other callers. It stops short of covering failure modes (invalid/expired ticket) or removal, leaving a small but real gap.

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

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

Schema description coverage is 100%, so the single 'ticket' parameter is already documented in the schema. The description adds only that it is 'supplied' to the session rather than any format, sourcing, or validity detail beyond the schema.

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

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

States a specific verb and resource ('Supply an iRODS ticket to the caller's iRODS session'), clearly distinguishing it from siblings like ds_create_ticket, ds_modify_ticket, and ds_get_ticket_info. The description could be sharper about what 'supply' changes, but an agent can identify the operation without opening the schema.

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

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

The description implies usage via 'subsequent operations by the same caller run with the ticket applied,' which tells the agent this affects later calls in the session. However, there is no explicit when-to-use vs. when-not, no mention of needing a ticket from ds_create_ticket first, and no stated alternatives.

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

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

No annotations are provided, so the description must carry the full behavioral burden. It does not disclose whether writing overwrites existing content, whether the file must already exist, what permissions are required, or what errors can occur. The max size and iRODS path constraint are mentioned but are not enough 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?

The core action is front-loaded in the first sentence, which is good. However, the third sentence about displaying large files and WebDAV URIs is irrelevant to a write operation and adds confusion rather than value.

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

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

For a write tool with no annotations and no output schema, the description leaves critical gaps: it does not explain overwrite semantics, required permissions, or return behavior. It is not complete enough for an agent to invoke confidently in varied scenarios.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds only that the path must be an iRODS path, which is a minor constraint beyond the schema text. 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?

States a specific verb ('Write') and resource ('partial content to a file (data-object)') with path and offset. It does not distinguish itself from likely siblings like ds_upload_file or clarify how partial writes differ from full uploads, so it falls short of a 5.

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

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

No guidance on when to use this tool versus alternatives such as ds_upload_file or ds_read_file. The third sentence about WebDAV URI for large files is about reading, not writing, and does not help select 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?

With no annotations, the description carries the full burden and does well: it discloses validation, the AVU write with naming modes, and the non-obvious DuckLake snapshot side effect. It omits permissions/auth requirements, failure behavior, and reversibility, keeping it short of a 5.

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

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

One dense sentence with the primary action front-loaded and zero filler. Every clause (validate, write AVUs, mirror) 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 mutating pipeline tool with a nested record object and no output schema, the description adequately covers the operations performed. It could mention validation-failure behavior or prerequisites, but nothing critical to 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 target, record, and naming. The description restates the naming variants but adds no format, syntax, or constraint details beyond the schema. Baseline 3 applies.

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

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

States specific verbs (validate, write, mirror) and resources (DataCite 4.x record, iRODS AVUs, DuckLake snapshot). It is clearly distinguishable from siblings like mesa_datacite_validate (validation only) and ds_add_avus (generic AVU write).

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

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

No when-to-use or when-not-to-use guidance is given, and no alternative is named despite several plausible siblings (mesa_datacite_validate, ds_add_avus, mesa_avu_apply_term). Usage must be inferred from the pipeline verbs alone.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose two distinct side effects: a write to the iRODS path and a recorded change in the project's DuckLake. That dual-mutation disclosure is genuinely useful. However, it says nothing about required permissions, atomicity/partial-failure behavior if term resolution or the DuckLake write fails, or idempotency, which are the traits an agent most needs for a multi-system mutation.

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

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

Two sentences, zero filler, front-loaded with the operation and its outputs, with the sibling-relationship detail placed last where it belongs. Every clause earns its place.

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

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

For a six-parameter, no-output-schema, no-annotation mutation tool, the description covers the full execution path and the shape of what gets written, which is the essential information. It leaves minor gaps around return values and failure semantics, but nothing critical 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%, so the baseline is 3, but the description adds real meaning by explaining how parameters combine: ontology_id and label form the attribute as <ontology>.<snake_label>, and the CURIE is carried as the third triple element. That clarifies the relationship between ontology_id, label, curie, and value in a way the flat schema does not.

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?

Names a concrete pipeline of verbs (resolve, build, write, record) against a specific resource (an AVU triple on an iRODS path plus a DuckLake ledger). It also positions itself against siblings by declaring it is a composite of mesa_avu_from_term + ds_add_avu, so an agent can distinguish it from those two tools without opening a schema.

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

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

The phrase 'Composite of mesa_avu_from_term + ds_add_avu, in one call' clearly signals when to reach for this tool rather than invoking the two primitives separately. It stops short of explicit exclusions (e.g. when a caller only wants resolution without writing, or wants a raw AVU without ontology lookup), so it is clear context rather than full when/when-not guidance.

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

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

With no annotations, the description carries the full burden and does disclose the key side-effect profile ('Pure transformation', no iRODS write) plus the exact output structure (attribute/value/unit). It omits whether an OLS network lookup occurs and any error behavior, leaving a modest gap.

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

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

A single dense sentence with the transformation and the no-write constraint front-loaded; every clause earns its place with no filler.

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

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

There is no output schema, so the description correctly compensates by describing the returned triple. Combined with the thorough input schema this is nearly complete, though OLS lookup/fallback behavior is left to 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 100%, so all five parameters are already documented, including the iri/curie/label interplay. The description's attribute='<ontology>.<snake_case_label>' and unit=<CURIE> mapping adds useful framing but mostly restates 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?

States a precise verb and transformation ('turn an OLS term + user value into the canonical AVU triple') and even spells out the resulting triple shape. The phrase 'without writing to iRODS' cleanly separates it from the write-oriented sibling mesa_avu_apply_term.

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 'Pure transformation ... without writing to iRODS' framing tells the agent this is for computing an AVU triple rather than persisting one, implicitly steering toward mesa_avu_apply_term for writes. It never names the alternative explicitly or states exclusions, so it stops short of a full 5.

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

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

With no annotations, the description carries the full burden, and it does disclose the two output serializations and the DataCite schema version. However, it omits whether the operation is side-effect free, what happens with malformed or non-canonical AVUs, and whether validation occurs during export.

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 sentence with the action front-loaded and no filler; the parenthetical adds the use case compactly. It is appropriately sized for a two-parameter transformation 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?

No output schema and no annotations, so the description must carry everything. It covers the output format dimension adequately but leaves the agent without guidance on sequencing with sibling validate/template tools or on failure behavior.

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 50%: the avus parameter is documented in-schema but format has no description. The description compensates partially by naming both xml and json outputs, matching the enum, but adds no detail on how AVU attribute/value/unit map into the emitted document.

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

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

States a specific verb ("Export") and resource ("DataCite AVUs") plus the two concrete output artifacts (DataCite 4.x XML, REST JSON), which is far more informative than the bare tool name. It does not explicitly name or contrast with siblings like mesa_datacite_validate or mesa_datacite_template, so an agent must infer the boundary.

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 parenthetical "(for DOI registration)" implies a use case for the XML format, but there is no explicit when-to-use, when-not-to-use, or named alternative. Nothing tells the agent whether to validate first with mesa_datacite_validate or to prefer this over mesa_datacite_template.

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 supplied, so the description carries the full behavioral burden. It does disclose the shape of the returned payload (the scaffold columns), which is genuine behavioral context, but it never states that the call is a static, side-effect-free read with no auth or mutation implications. For a zero-parameter static tool the omission is low-risk but still a 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 front-loaded sentence with the verb and resource first and the payload detail in a parenthetical. It is dense but every clause earns its place; the parenthetical enumeration is slightly heavy but still readable.

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

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

With no output schema, the description must convey the return shape, and it does list the scaffold's fields. What is missing is confirmation that the result is static and requires no input, which the input schema states but the description does not reinforce.

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 are zero parameters, so the 4 baseline applies and the description correctly needs to add no parameter detail. The schema additionally documents that no input is required, so nothing is left ambiguous.

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 ('Return') and resource ('DataCite 4.x field scaffold') and enumerates the contents of that scaffold (field, required?, repeatable?, controlled vocabulary, canonical AVU key). It does not, however, differentiate itself from close siblings such as mesa_ols_generate_template or mesa_datacite_export, so an agent must infer which one to call.

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

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

The trailing phrase 'to drive a complete, valid record' implies the intended context — use it as a planning/scaffolding step before building or validating a record — but there is no explicit when-to-use rule, no exclusions, and no named alternative. Usage 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?

With no annotations, the description carries the full burden, and it does disclose the outcome behavior (reports missing mandatory fields, invalid vocabulary, DOI-readiness) and the 4.x kernel scope. It does not explicitly state it is read-only/non-mutating or mention any auth requirements, which is the only 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 front-loaded sentence that names the operation first and then the report contents; 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?

For a single-parameter validation tool with no output schema, the description adequately covers what is checked and the reporting outcome. It stops short of clarifying error/failure behavior or the exact shape of the returned report, but is sufficient to invoke 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?

One parameter at 100% schema coverage including an inline description ('The candidate DataCite AVUs to validate'), so the schema does the heavy lifting. The description adds only the DataCite 4.x kernel context, not syntax or format detail. 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 (validate) and resource (DataCite AVUs against the 4.x kernel), and enumerates exactly what it reports: missing mandatory fields, invalid controlled-vocabulary values, and DOI-readiness. An agent can immediately tell this apart from the apply/export/template 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?

There is no explicit when-to-use or when-not guidance. It is only implied that validation precedes something like mesa_avu_apply_datacite, and no alternatives are named or excluded.

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 and does a solid job: it discloses the three concrete side effects (sub-collection creation, AVU write, catalog registration) and explicitly states the tool is idempotent and safe to re-run. It stops short of stating required permissions or what happens if the path does not exist.

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

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

Two sentences, zero filler, with the core action front-loaded and the operational caveat (idempotency) placed last. Every clause conveys a distinct fact.

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

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

For a single-parameter mutation tool with no annotations and no output schema, the description covers the essential behavior and idempotency. It could be more complete by stating permission requirements and the failure mode for an invalid or nonexistent path, but nothing critical 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?

Only one parameter exists and schema description coverage is 100%, so the schema already explains that irods_path is the root collection carrying the AVU. The description restates the same concept in prose ('project root') without adding format, constraint, or default details beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Enroll an iRODS collection as a MESA project') and then enumerates the concrete artifacts created (the .mesa/ducklake sub-collection, the mesa.enabled=true AVU, the DuckLake catalog registration). It is unambiguous what the tool does, though it never contrasts itself with adjacent siblings like mesa_policy_enable or ds_make_directory, which also touch collections and metadata.

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 'Enroll an iRODS collection as a MESA project' and the idempotency note tells the agent re-running is safe, but there is no explicit when-to-use framing, no prerequisites (e.g. that the collection must already exist), and no named alternative for related setup tasks. Adequate but leaves the routing decision to inference.

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

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

No annotations are supplied, so the description carries the full disclosure burden. It never states whether the tool only computes a template or persists/writes anything, whether there are side effects, whether an existing ontology is required to be loaded, or what the returned object looks like. 'Drives the ... auto-generated AVU forms' hints at a derived artifact but leaves the mutation/reversibility profile unclear.

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

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

Two short sentences, front-loaded with the concrete deliverable before the downstream rationale. No filler, though the second sentence is arguably context rather than actionable instruction.

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?

There is no output schema, so the description must describe the return value; it partially does ('prefix + top-level term fields'), which is the most valuable part. However, it omits any behavioral or usage detail, leaving the definition only minimally sufficient for a no-annotation, no-output-schema tool.

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

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

Schema description coverage is 100% and there is a single required parameter (ontology_id) already documented with an example in the schema. The description does not add syntax or semantic detail about the parameter, so the baseline of 3 applies.

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

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

States a specific verb ('Generate') and a well-defined resource ('a SCHEMAS-compatible template (prefix + top-level term fields) for an ontology'), and adds the downstream purpose (driving esiil-portal AVU forms). It is clear what the tool produces, though it never distinguishes itself from the similarly named sibling mesa_datacite_template.

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 context about what the output feeds into but provides no when-to-use guidance, no prerequisites, and no mention of alternatives such as mesa_datacite_template or mesa_avu_from_term. An agent must infer the usage context entirely.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Fetch' implies a read-only lookup, and the listed metadata fields clarify the return content, but there is no mention of error behavior, authentication, rate limits, or what happens if the ontology does not exist. The description adds basic context but not complete behavioral transparency.

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

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

The description is a single, front-loaded sentence with no wasted words. It states the operation, scope, and returned fields efficiently. Every part of the 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?

The tool is simple, requires one well-described parameter, and has no output schema. The description compensates by enumerating the metadata fields returned, which is the main missing context. It could say more about failure behavior or being read-only, but for this low-complexity lookup it is nearly complete.

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

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

Schema description coverage is 100%, and the ontology_id parameter is documented with examples and a case-insensitivity note. The description adds no parameter meaning beyond the schema, so the baseline score 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 uses a specific verb, 'Fetch', and a precise resource, 'metadata for a single OLS ontology'. It also lists the returned metadata fields, making clear this is not a term-search or list operation. The word 'single' distinguishes it from the sibling mesa_ols_list_ontologies.

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

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

The description implies usage: fetch this when you need metadata for one ontology. However, it does not explicitly state when to choose this over alternatives such as mesa_ols_list_ontologies or mesa_ols_get_term. No when-not or prerequisite guidance is provided.

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 does disclose the response payload contents (label, CURIE, synonyms, definition, parents/children), which is the most valuable thing here given there is no output schema, but it says nothing about error behavior for an unknown IRI, required permissions, or rate limits.

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

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

A single front-loaded sentence with zero filler; the resource and lookup key come first and the returned fields follow as a compact parenthetical.

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

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

For a two-parameter read tool with no output schema, listing the returned fields compensates well for the absent return-value documentation. The remaining gap is behavioral (error handling, permissions), which matters slightly more because there are no annotations to fall back on.

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%, with the iri parameter documented including a concrete example, so the schema already does the heavy lifting. The description only restates 'by IRI' and adds no format, casing, or ontology_id/iri relationship detail 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?

Specific verb (get) plus resource (single OLS term) and it enumerates the returned record fields (label, CURIE, synonyms, definition, parents/children). It is clearly distinguishable from search-style siblings, but it never names mesa_ols_search_terms or mesa_ols_get_term_hierarchy, so differentiation is left to inference.

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

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

Usage is only implied: 'by IRI' signals that this is a direct lookup when the identifier is already known, which contrasts loosely with mesa_ols_search_terms. There is no explicit when-to-use/when-not statement, no guidance on where to obtain the IRI, and no mention of the hierarchy sibling that also returns parents/children.

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 usefully discloses that it returns only *direct* children (non-recursive, one level), which is real behavioral information, but it says nothing about read-only safety, pagination/truncation from the size cap, ordering, or failure modes for an invalid IRI.

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, zero waste, with the core action ('list direct children') front-loaded. Nothing repetitive or filler.

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

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

With no output schema and no annotations, the description should carry more of the contract. It conveys the essential return (direct children) but omits the shape of a child entry and, critically, what happens when the size cap is reached, which matters for a traversal tool.

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

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

Schema description coverage is 100%, so iri, ontology_id, and size are all documented in the schema itself. The description adds only the implicit notion that iri is the parent term; it adds no format, syntax, or edge-case guidance beyond the schema baseline.

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

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

States a specific verb and resource ('List the direct children of an OLS term') and scopes it to one level of an ontology hierarchy. It is clear what the tool returns, though it does not name the sibling (mesa_ols_get_term) it is adjacent to, so an agent must infer the boundary from the tool name.

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

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

'Use this to walk an ontology's class hierarchy one level at a time' gives a concrete usage context: iterative traversal of a hierarchy. It does not name explicit alternatives (e.g. mesa_ols_get_term for a single term, or mesa_ols_search_terms), so there are no stated exclusions, but the intended scenario is 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose two useful traits — results are paginated and the corpus is 266+ ontologies — but says nothing about rate limits, authentication, or the shape of each returned ontology record.

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

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

Two tight sentences, front-loaded with the action and service, followed by the payoff (count and example ontologies like ENVO, GO, CHEBI) that helps an agent confirm it found the right catalog. 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 read-only, zero-required-parameter list tool with fully documented params and no output schema, the description is nearly sufficient. The one gap is that it never hints at what an ontology entry contains (id, title, prefix), which would help the agent use the 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%, with both page and size fully documented in the schema including defaults and bounds (1–200). The description adds only the word "paginated," which the schema already conveys, so the baseline 3 is correct.

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

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

States a specific verb and resource ("List ontologies") plus the backing service (EMBL-EBI OLS4), which cleanly separates it from the singular sibling mesa_ols_get_ontology. It stops short of explicitly naming that sibling or any other alternative, so differentiation is implied by wording rather than stated.

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

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

Usage is only implied: an agent can infer this is the entry point for discovering which ontologies exist before drilling into terms or a single ontology. There is no explicit when-to-use, when-not-to-use, or pointer to mesa_ols_get_ontology / mesa_ols_search_terms as follow-ups.

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

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

With no annotations, the description carries the full behavioral burden, and it discloses almost nothing beyond the operation itself: no result ordering, ranking, pagination, or the fact that the hierarchy walk requires ontology_id to be meaningful. The one useful behavioral hint ('hierarchy walk') is thin.

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

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

Two short sentences, front-loaded with the core operation and followed immediately by the optional narrowing behavior. No filler, no restatement of the tool 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?

For a search tool with full schema coverage and no output schema, the description is minimally sufficient to select and call the tool. It is missing return-behavior context (ordering, result shape, default limit semantics) that the absent annotations and output schema leave uncovered.

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 schema already documents query, size, ontology_id and descendants_of (including the allChildrenOf compatibility note). The description adds only the 'hierarchy walk' framing and does not clarify the ontology_id + descendants_of interaction beyond what the schema says.

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 (search) and resource (OLS terms) and adds scope framing ('across all ontologies or scoped to one'), which separates it from sibling readers like mesa_ols_get_term and mesa_ols_get_term_hierarchy. It does not 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?

The description implies when the scoping and descendant options apply, but that is essentially a restatement of the schema parameters rather than independent usage guidance. There is no explicit when-not or pointer to the alternative tools (get_term, get_term_hierarchy) an agent should consider.

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

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

With no annotations, the description carries the full burden, and it does disclose the concrete side effect of removing a specific AVU plus a conditional secondary effect (recording into DuckLake when MESA-enabled). However, it omits permission/auth requirements, idempotency behavior when the policy is absent, and error semantics 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 tight sentences with zero filler; the action and its mechanism are front-loaded, and the conditional DuckLake side effect is appended where it belongs.

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

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

For a two-parameter mutation with no annotations and no output schema, the description covers the core action and the AVU mechanism adequately, but leaves the agent without return-value expectations, failure modes, or prerequisites needed to invoke it confidently.

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 parameters are already documented with their formats and the AVU suffix convention. The description restates the same mesa.policy.<name> mapping the schema already provides, adding no new syntax or format detail.

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

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

The description names a specific verb ('Disable') and resource ('a MESA policy on a project root collection') and even states the underlying mechanism (removing the mesa.policy.<policy_name> AVU), which clearly separates it from mesa_policy_enable. It stops short of explicitly naming the enable counterpart as an alternative, but the operation is 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?

Usage is only implied: the agent can infer this is the tool for turning a policy off, but there is no explicit statement of when to prefer it over mesa_policy_enable, nor any preconditions (e.g. the policy must already be applied, MESA must be initialized). No when-not guidance.

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

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

With no annotations, the description carries the full behavioral burden. It does well to disclose the concrete side effect (AVU write) and the conditional DuckLake record-keeping, but omits idempotency (what if the policy is already enabled), required permissions, and error behavior on a non-existent path.

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 tightly packed sentences with zero filler; the enable mechanism is front-loaded and the secondary DuckLake note follows. Nothing is repeated or wasted.

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

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

For a two-parameter toggle with no output schema, the description covers what happens on success (AVU written, DuckLake updated if MESA-enabled). It falls just short of complete by not covering failure modes or confirmation of the resulting state.

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 both parameters fully. The description restates the policy_name-to-AVU-suffix mapping rather than adding new format or validation meaning, so the baseline of 3 applies.

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

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

States a specific verb (Enable), a specific resource (a MESA policy on a project root collection), and the exact mechanism (writing mesa.policy.<policy_name>=true AVU). The inversion against the sibling mesa_policy_disable is unambiguous from the verb plus the hardcoded '=true' value.

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 — enabling a policy for a project root — but the description gives no explicit when/when-not guidance, no prerequisite checks (e.g., inspecting with ds_list_policies first), and does not name the alternative tool for the inverse operation.

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