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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds that the analysis includes relationship mapping and validation, which clarifies the scope, but it does not disclose output shape, error behavior, or side effects beyond what annotations imply.

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, resource, and key scope are stated immediately, and every word carries meaning.

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

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

The tool has no output schema and overlapping siblings, but the description does not explain what the analysis result contains, how validation is reported, or when to prefer this tool. An agent would likely need to call it blindly or rely on tool names alone.

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 collection, includeRelations, and validateConstraints. The description does not add extra parameter semantics beyond the tool's general purpose, 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?

Description uses a specific verb ('Analyze') and target ('collection schema') and names the two core activities: relationship mapping and validation. It is clear, but it does not differentiate itself from sibling tools like analyze_relationships or validate_collection_schema, which overlap with those activities.

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 is given about when to choose this tool over siblings such as get_collection_schema, analyze_relationships, or validate_collection_schema. The description does not mention use cases, preconditions, or 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?

The annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only behavior is covered. The description adds the cross-collection scope but does not disclose what the analysis returns, what inputs trigger different behavior, or any operational constraints. No contradiction with annotations exists.

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

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

The description is extremely short and easy to parse, but it reads as under-specified rather than deliberately concise. It contains no behavioral or return-value information that would help an agent invoke the tool correctly.

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 clarify what the tool returns or how the analysis is presented, but it does not. The ambiguity around sibling tools and the absence of usage guidance leave the description incomplete for reliable tool selection.

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

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

The input schema provides complete descriptions for both parameters, collection and includeSystemCollections, so structured coverage is 100%. The description adds no extra semantic meaning beyond what the schema already communicates.

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 action, 'analyze', and a resource, 'relationships', with the scope 'across collections'. However, it does not differentiate this tool from the sibling analyze_collection_schema, so an agent may struggle to choose between them.

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

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

There is no guidance about when to use this tool versus alternatives like analyze_collection_schema, validate_collection_schema, or search_tools. The description states only what the tool does, with no mention of conditions, exclusions, or better-suited alternatives.

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

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

Annotations already declare destructiveHint=true, but the description adds concrete specificity: applying the schema 'can drop collections and fields.' That is valuable beyond the generic destructive flag. It also clarifies that this changes the live data model, not a draft or preview. No contradiction with annotations.

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

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

Two tightly packed sentences with no filler. The core action and source of input are front-loaded, and the destructive consequence is positioned immediately after the action. Every word earns its place.

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

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

For a destructive, live-altering operation with three parameters and no output schema, the description covers the key decision factors: what the input is, what it does, and its destructive potential. The schema covers parameter-level details, and annotations cover the destructive hint. A small gap is not mentioning that applied changes may be irreversible or that confirmation parameters exist, but the overall context is sufficient for correct tool selection and invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that the diff parameter is the output of diff_schema, but it does not add substantive semantics for force or confirm beyond what the parameter descriptions already provide. It is adequate but not additive.

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 action ('Apply') on a precise resource ('a schema diff produced by diff_schema'), and clearly distinguishes its role from diff_schema, which produces the diff. It also conveys the high-impact nature of the operation, so an agent can immediately tell this is the apply step rather than a preview or validation step.

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 establishes the prerequisite by saying the diff must come from diff_schema, which implies the correct workflow: run diff_schema first, then apply_schema. It does not explicitly name alternatives or state when not to use the tool, but the destructive warning and live-model language give enough context to avoid using it for read-only or validation purposes.

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

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

Annotations already convey mutability (readOnlyHint=false) and destructive potential (destructiveHint=true). The description adds that create, update, and delete can be carried out in one bulk call, which is useful behavioral context beyond the schema. However, it does not disclose validation semantics, partial-failure behavior, or irreversible consequences.

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

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

A single compact phrase with no filler; every word contributes to the core purpose. It is terse, but not bloated, and the main action is front-loaded.

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

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

Despite the tool being destructive, supporting a nested operations object, and having no output schema, the description gives no guidance about execution semantics, return values, error behavior, or validate effects. The structure and annotations carry most of the context, leaving meaningful gaps for a calling agent.

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

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

Schema descriptions cover collection ('Collection name'), operations subfields ('Items to create/delete/update'), and validate ('Validate operations before execution'), so the burden on the description is modest. The description itself adds no parameter-level meaning, and the 'collection' parameter description is minimal.

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 action ('Execute bulk create, update, and delete operations') and clearly identifies the resource category, distinguishing it from sibling tools like create_item, update_item, and delete_items. It is not tautological, though it could be slightly more specific about the collection context.

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 word 'bulk' implies this tool is for batch operations rather than individual item tools such as create_item or delete_items, but there is no explicit when-to-use guidance, exclusions, or alternatives mentioned. The usage context is inferable, not directly stated.

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

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

Annotations already signal a write operation (readOnlyHint=false) and non-destructive behavior, so the description adds useful operational context: it creates a real table and defaults to an auto-increment id when fields are omitted. The folder branch is also disclosed, which helps the agent understand the side effects of each call.

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

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

Two sentences with no filler: the main purpose is front-loaded and the conditional behavior is compressed into a single follow-up sentence. 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 creation tool with one required parameter and clear schema coverage, the description is mostly complete. Minor gaps remain: it doesn't describe the expected return value or the structure of the optional fields array, and it could point to create_field or validate_collection_creation, but these do not block correct invocation.

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

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

Schema coverage is 100%, giving a baseline of 3; the description adds value by defining the conditional behavior of the fields and folder parameters (no fields -> auto-increment id; folder:true -> grouping element). It doesn't detail the shape of nested field objects, but that is not required for a basic call and the schema already labels each parameter.

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 and resource ('Create a new collection') and immediately disambiguates the two main modes: a real table with an auto-increment id or a folder grouping element. This clearly separates it from sibling tools like create_field or delete_collection.

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 clearly establishes when to use it: creating a new collection, with optional fields. It also explains the folder alternative as an in-tool option. It does not explicitly name sibling alternatives such as create_field or validate_collection_creation, but the context is clear enough that an agent won't confuse it with another tool.

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

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

The description adds no behavioral context beyond what the annotations already convey. While annotations indicate readOnlyHint=false and destructiveHint=false, the description does not explain side effects like schema changes, permissions required, or behavior when the field already exists. It neither contradicts annotations nor enriches them.

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 clear sentence with no wasted words, making it easy to read and front-loaded. It is appropriately concise, though it sacrifices informative richness 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?

Despite having 10 parameters, nested objects, and no output schema, the description provides only a bare statement of intent. There is no mention of return values, schema impact, required permissions, or potential failure modes. The tool's complexity demands more context than this minimal description supplies.

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 parameters are already documented in the input schema. The description adds only minimal context ('field' and 'collection'), but does not meaningfully enhance understanding of optional parameters like options, validation, or interface. Baseline 3 applies due to complete schema coverage.

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

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

The description states a specific action (create) and resource (a new field in a collection), which clearly distinguishes it from sibling tools like update_field, delete_field, and create_collection. It unambiguously communicates what the tool does.

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

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

The description provides no guidance on when to use this tool versus alternatives such as update_field, delete_field, or create_relationship. There is no mention of prerequisites, exclusions, or context that would help an agent choose this tool over a sibling.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description does not need to state that this tool mutates. However, the description adds no behavioral detail beyond the obvious creation action. It does not disclose side effects, validation behavior, whether duplicate names are allowed, the default status (active), or anything about how the flow is initialized.

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

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

The description is a single, concise sentence with no wasted words. It front-loads the core action and resource, which is appropriate for a simple create operation.

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

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

Despite the tool having 6 parameters, nested operation objects, and no output schema, the description explains none of the domain-specific details. An agent is left without information about how operations should be structured, what options are valid, whether trigger is needed, what the response will be, or any constraints on valid flow creation.

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

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

The input schema has 100% description coverage, so the schema already documents all parameters. The tool description itself adds no parameter-level meaning, but the baseline for high schema coverage is 3, and the description does not need to compensate.

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 'Create a new automation flow' uses a specific verb ('create') with a clear resource ('automation flow'), making the tool's purpose immediately obvious. It distinguishes itself well from sibling tools like update_flow, delete_flow, trigger_flow, and other create_* tools such as create_item and create_collection.

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 is provided about when to use this tool versus alternatives. There is no mention of prerequisites, when an existing flow should be updated instead, or how the tool relates to trigger_flow or bulk_operations. The only usage signal is the verb 'create', which is too minimal to help an agent decide among the many sibling tools.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutating nature is implied. However, the description adds no behavioral context beyond the act of creating—no mention of validation, permissions, idempotency, side effects, or what happens with the data object.

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, direct sentence with no redundant words. It is front-loaded and easy to parse, though slightly sparse for a tool with nested object parameters.

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

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

For a simple two-parameter create operation, the description is minimally adequate. However, it lacks details about return values, error behavior, or whether the data object must match a schema, which could matter for an agent invoking the tool correctly.

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

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

Both parameters are documented in the schema with clear descriptions ('Collection name', 'Item data'), giving 100% schema coverage. The description does not add any meaning beyond the schema, 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 ('Create') and resource ('a new item in a collection'), making the tool's purpose immediately clear. It also distinguishes itself from sibling tools like update_item and delete_items by focusing on creation of new items rather than modification or deletion.

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 verb 'Create' implies this tool is for adding new items, but the description does not explicitly state when to prefer it over alternatives or provide exclusions. There is no mention of prerequisites, such as the collection existing, or guidance on when to use update_item instead.

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

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

Annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) already establish this as a mutating but non-destructive operation, and the description is consistent with them — no contradiction. However, the description adds no behavioral context beyond that: no mention of auto-created junction collections for M2M, effects on existing data, validation requirements, or failure modes. It merely restates the relationship-type enum already present in the schema.

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

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

The description is a single tightly structured sentence with the verb front-loaded and the relationship types in a scannable parenthetical. It loses one point because the parenthetical repeats the schema's already-documented enum values, making a small portion of the text redundant rather than adding 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?

This is a 14-parameter tool with five distinct modes, each requiring different parameter subsets (junction fields for M2M, allowed_collections/collection_field/primary_key_field for M2A), and no output schema. A single sentence does not explain which parameters apply to which mode, prerequisites, or side effects. An agent would need deep schema inspection and external knowledge to configure a correct call, so the description is inadequate for the tool's complexity.

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 14 parameters are documented in the schema itself, earning the baseline of 3. The description adds no meaning beyond the schema — the (O2O, O2M, M2O, M2M, M2A) list merely duplicates the 'type' enum — and it does not explain how parameters interact per relationship type, such as which fields are required for M2M vs M2A.

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 ('Create') and resource ('relationships between collections') and enumerates the five supported relationship types, which clearly separates it from siblings like create_collection, create_item, and create_field. It stops short of a 5 because it doesn't explicitly contrast itself with related tools like analyze_relationships or update_field, which also touch relationships.

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 is given on when to use this tool versus alternatives. It doesn't mention that analyze_relationships is for inspecting existing relationships, that update_field handles schema modifications, that prerequisites (existing collections) may apply, or any exclusions. The type list implies broad coverage but gives an agent no routing 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?

The description adds the behavioral claim that confirmation is required, but the input schema marks confirm as optional, creating ambiguity about whether deletion can proceed without it. No further context is provided about irreversibility, cascading deletion of collection contents, or permissions, which the annotations do not cover.

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 filler. Every word earns its place, and the parenthetical adds the one behavioral note without bloating the text.

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

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

For a destructive tool, the annotations carry the safety profile and the schema covers both parameters. However, the description could do more: it does not state whether deletion is permanent/cascading, whether confirm must be true, or what response to expect, leaving an agent to infer the semantics from 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 the baseline is 3; the description itself adds no parameter details beyond echoing the confirmation concept. This is sufficient for distinguishing collection and confirm, though it does not resolve the confirm-required ambiguity.

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 phrase 'Delete a collection' uses a specific verb and resource, clearly distinguishing this from sibling tools like delete_items, delete_flow, and delete_field. The parenthetical about confirmation does not obscure the core purpose.

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 prefer this tool over alternatives such as delete_items, create_collection, or bulk_operations. The description only restates the operation and gives no conditions, exclusions, or related-tool routing.

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

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

Annotations already declare destructiveHint=true, and the description adds the important behavioral guard that confirmation is required before deletion. This goes slightly beyond the schema's confirm parameter by indicating that the action will not proceed without that confirmation.

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 states the core action and the critical precondition with zero wasted words. It is appropriately sized for the tool's simplicity.

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 destructive delete operation with a destructiveHint annotation, the description covers the essential behavior and confirmation guard. It does not mention irreversibility or access requirements, but the annotation and simple nature of the tool make the description sufficient.

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 little beyond the confirmation requirement, which is effectively restating the confirm parameter's purpose.

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: 'Delete a field from a collection.' This clearly distinguishes it from sibling operations like create_field, update_field, and delete_collection, so an agent can understand exactly what the tool does.

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

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

The description implies when to use the tool (removing a field requires confirmation), but it does not explicitly contrast with alternatives or explain when not to use it. The confirmation requirement provides some usage context, but no direct exclusions or alternative routing.

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

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

Annotations already mark the tool destructive and non-read-only; the description adds value by disclosing the cascade to operations and the confirmation requirement. It accurately matches the destructiveHint and does not contradict any annotation.

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

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

One short sentence front-loads the action and packs the essential nuances (cascade and confirmation) into a parenthetical. No wasted words; the description is easy to scan.

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

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

For a two-parameter destructive tool with high schema coverage and destructiveHint set, the description conveys the fundamental behavior: deletion target, cascade scope, and confirmation. Minor omission: the effect of confirm=false/omitted isn't stated, which could matter to an agent deciding whether to request confirmation.

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 id and confirm. The description reinforces that confirmation is expected and adds the cascade-to-operations context, but it doesn't clarify what happens when confirm is false or absent.

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), a clear resource (a flow), and a defining scope nuance (and all its operations). The cascade detail differentiates it from sibling flow tools like update_flow or trigger_flow, and from other delete 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 description makes the core use case obvious ('Delete a flow') and flags confirmation, but it does not explicitly state when to prefer this tool over update_flow, trigger_flow, or delete_collection. Usage context is implied by the action rather than spelled out.

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

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

Annotations already carry destructiveHint=true and readOnlyHint=false, so the destructive profile is known without the description. The description does add one useful behavioral disclosure beyond annotations — 'Providing neither deletes nothing' — which guards against accidental mass deletion or no-ops. It does not discuss irreversibility, permission requirements, or side effects, so added value is modest.

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 and roughly 20 words, with the core verb-resource pair front-loaded in the first sentence. The second sentence is a high-value safety note that earns its place. No redundancy 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?

For a destructive 5-parameter tool with full schema coverage and strong annotations, the combined description and schema cover the two deletion modes, mutual exclusivity, the bulk-delete escape hatch, and the no-op guard. Minor gaps remain: whether confirm is mandatory for deletion and that deletions are permanent are left to inference, but nothing critical blocks correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description reinforces the ids-vs-query relationship and the no-op guard, but the schema already documents every parameter, including mutual exclusivity of ids and query and the { 'limit': -1 } bulk-delete escape hatch. The description adds little 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 (Delete), a clear resource (items from a collection), and the two selection modes (explicit IDs or query). 'Providing neither deletes nothing' sharpens the scope beyond a generic delete. It is readily distinguishable from delete_collection in the sibling list, which targets collections rather than items.

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 conveys the two mutually exclusive selection modes and the safe no-op case, which implies when the tool applies. However, it never explicitly names alternatives or exclusion conditions, such as 'use delete_collection for whole collections' or 'use update_item for edits.' Usage context 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?

Annotations already declare readOnlyHint and openWorldHint, so the description does not need to restate safety. 'Diagnose' is consistent with the read-only annotation and adds the scope of investigation, though it does not disclose output format, limits, or side effects. No contradiction.

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

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

A single, front-loaded sentence with no filler words. It is appropriately brief, though it is too terse to carry richer context; this is efficient rather than exceptional.

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 diagnostic tool with fully documented parameters, this is minimally adequate: an agent can identify the collection and optional checks to run. However, there is no output schema and the description does not describe the diagnostic result or how to interpret it, leaving a meaningful gap.

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

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

Schema description coverage is 100%, and each parameter already has a clear meaning in the input schema. The description adds no parameter-level detail, 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 clear verb ('diagnose') applied to a specific resource ('collection access issues and permissions'). This distinguishes it from sibling tools like analyze_collection_schema and analyze_relationships, which target schema or relationships rather than access controls.

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 usage guidance is provided: the description does not say when to choose this tool over alternatives, when not to use it, or what prerequisites are required. The only guidance is implied by the word 'diagnose', which is weak given the large set of sibling diagnostic tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description reinforces rather than contradicts them ('Read-only — nothing is modified'). It adds the key behavioral context that the tool computes a hypothetical diff rather than mutating state. However, it does not disclose additional traits such as the version/vendor checks that the 'force' parameter bypasses or the structure of the reported operations. No annotation contradiction.

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

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

Two short sentences with the main action front-loaded immediately. The second sentence, 'Read-only — nothing is modified,' is somewhat redundant with the readOnlyHint annotation but serves as a quick safety reinforcement. No wasted words; appropriately sized.

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 three-parameter, read-only diff tool, the combination of description and schema covers what agents need: the purpose, the safety profile (annotations), parameter semantics (schema), and the snapshot source (schema references get_schema_snapshot). A return-format note would add polish, but nothing essential to calling 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%: mode explains mirror vs merge semantics, force describes bypassing version/vendor checks, and snapshot references get_schema_snapshot as its source. Since the schema already carries full parameter documentation and the description adds no parameter-level meaning, the baseline 3 applies.

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

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

The description states a specific verb+resource pair ('Compare a schema snapshot against the current data model') and the outcome ('report what applying it would change'). This clearly distinguishes it from siblings like apply_schema (which performs the mutation) and get_schema_snapshot (which produces the snapshot input). An agent can tell it apart 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 phrasing 'report what applying it would change' implicitly establishes this as a preview/dry-run step before apply_schema, and 'Read-only' signals it is not a mutator. However, no alternative tool is named explicitly, and the sibling list contains several adjacent tools (analyze_collection_schema, validate_collection_schema, get_collection_schema) with no differentiation. Usage context is clear but routing is left to inference.

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

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

The readOnlyHint and openWorldHint annotations already cover the safety profile, and the description is consistent with a read operation. It does not add deeper behavioral context such as version/draft semantics, raw delta behavior, or response format, so it earns a mid score.

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 filler. Every word contributes to understanding the tool's core purpose.

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

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

The description is adequate for basic selection, and the schema covers parameters well. However, with 9 parameters, versioned collection behavior, and no output schema, the description leaves semantic gaps around response shape and nuanced version/filter 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%, so the schema already documents all 9 parameters. The description only paraphrases filtering and pagination without adding substantive meaning beyond the schema, matching the baseline score.

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

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

The description states a specific verb and resource: get items from a collection. It clearly distinguishes from siblings like get_collection_schema, list_collections, and create_item by focusing on item retrieval.

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 use when retrieving items from a collection with filtering or pagination, but it does not explicitly contrast this with siblings such as get_collection_schema or analyze_collection_schema. Usage context is present only implicitly.

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

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

The readOnlyHint annotation already communicates that this is a safe read operation. The description adds no behavioral context beyond that: no indication of return format, error behavior, required permissions, or how the schema is structured. Since annotations cover only safety, the description carries little additional transparency value.

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 filler. For a simple one-parameter tool, this is appropriately sized and immediately communicates the action and target.

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 getter with one parameter and readOnlyHint/openWorldHint annotations, the description is functional but minimal. The lack of an output schema means the agent gets no guidance on the response shape, and the term 'schema' is not elaborated, which could cause ambiguity with related schema-analysis tools.

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 schema description covers 100% of the single parameter with 'Collection name,' and the description text adds no additional semantic detail. The baseline of 3 applies because the schema already fully documents the parameter.

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

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

The description clearly states the verb 'get' and the resource 'schema for a specific collection,' making the core purpose understandable. It does not explicitly differentiate itself from sibling tools like list_collections or analyze_collection_schema, though 'specific collection' narrows the scope.

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 'for a specific collection' implies this tool is for retrieving a single collection's schema rather than listing all collections. However, there is no explicit guidance about when to choose this over related siblings such as analyze_collection_schema or validate_collection_schema.

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

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

Annotations already declare readOnlyHint=true, so the safety profile of a read operation is covered. The description adds only that filtering and pagination are optional, which the schema already documents. No information about authorization, return format, or limitations is disclosed.

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 8-word sentence that front-loads the core purpose and adds no filler. Every word contributes, making it highly efficient.

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 list operation with 6 optional parameters and no output schema, the description is adequate but sparse. It doesn't mention that the operation is read-only (though annotations cover that), nor does it hint at the Directus file asset context beyond the title. It could mention alternative tools or parameter interpretation, but these are minor gaps.

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

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

Schema description coverage is 100%, so all six parameters are already described in the schema. The description adds no additional meaning about parameter usage, defaults, or relationships. Baseline 3 is appropriate when the schema carries the explanatory weight.

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?

Description clearly states the verb 'Get' and resource 'files', aligning with the title 'Directus - List Files'. It is unambiguous enough to distinguish from collection/user tools, though it doesn't explicitly contrast with sibling tools like get_collection_items.

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 get_files vs alternatives. The description only states what it does, not when to choose it. No exclusions or alternative references are present.

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

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

The readOnlyHint annotation already communicates that this is a safe read operation. The description adds that flow operations can be optionally included, which is useful response-shape context, but it does not disclose additional behavioral details such as return format or error behavior. No contradiction exists.

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

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

The description is a single, front-loaded sentence with no filler. It states the action and target immediately and remains appropriately sized for a simple two-parameter read tool.

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

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

For a low-complexity read tool with complete schema documentation and readOnly annotations, the description is largely sufficient. The main gap is the lack of explicit differentiation from related siblings like get_flows and get_operations, and 'operations' is not elaborated beyond the schema field description.

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

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

The input schema provides 100% coverage with descriptions for both parameters: 'Flow ID' and 'Include flow operations in response'. The description adds little beyond the phrase 'with optional operations', so the schema carries the semantic weight and 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'), a specific resource ('a specific flow'), and a selection criterion ('by ID'), which clearly conveys what the tool does. It is distinguishable from list-oriented siblings like get_flows, though it does not explicitly name an 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 intended use case is implied: retrieve a single flow when an ID is known, optionally including operations. However, the description does not explicitly explain when to use this tool instead of get_flows or get_operations, leaving 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?

The readOnlyHint and openWorldHint annotations already cover the safety profile, so the description adds little behavioral context beyond a basic restatement of filtering and pagination. It does not mention response shape, result limits beyond schema defaults, or any other runtime behavior.

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 efficient sentence that leads with the primary action 'Get flows' and then conveys the key optional capabilities. There is no filler, repetition, or 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?

The description is adequate for a straightforward read-only list tool with self-documenting parameters, and annotations cover the read-only nature. However, there is no output schema and no explanation of return format or pagination behavior, and the nested filter object is left vague, so the description alone is not 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?

Schema description coverage is 100%, so the input schema already documents all seven parameters. The description adds no additional parameter-level meaning beyond what the schema provides, which meets the baseline but does not exceed it.

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

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

The description clearly states the action ('Get flows') and the resource (flows), and the plural form implies list retrieval rather than a single flow. However, it does not explicitly distinguish itself from the sibling get_flow tool, so it lacks full sibling differentiation.

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

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

The phrase 'optional filtering and pagination' implies this tool is for listing multiple flows with constraints, which provides some usage context. But there is no explicit guidance on when to choose this over alternatives like get_flow or when filtering alone would be insufficient.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the description adds little beyond them. It repeats the filtering concept found in the schema and provides no additional behavioral context such as pagination behavior, ordering, or the meaning of 'operations.'

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 contains no filler or redundant wording. It is concise and readable, though it sacrifices useful detail 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 simple read-only tool with two optional parameters and annotations covering safety, the description is minimally viable. However, it lacks explanation of what an operation is, whether all operations are returned by default, and what the response looks like, which leaves clear gaps.

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

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

Schema coverage is 100%, with both parameters (limit and flow_id) having descriptions. The description only echoes the filter concept without adding new meaning, so it meets the baseline but does not improve on 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 clearly states a specific verb ('Get') and resource ('flow operations') with an optional filter. It distinguishes itself from siblings like get_flows and get_flow by naming operations specifically, though it does not explicitly differentiate from all alternatives.

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

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

There is no guidance on when to use this tool versus alternatives such as get_flows, trigger_flow, or bulk_operations. The only usage hint is 'optional filtering by flow,' which does not explain when filtering should be applied or how this compares to other tools.

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

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

Read-only behavior is already declared by readOnlyHint=true, and the description's 'Read' agrees with it. It adds useful context that the snapshot spans collections, fields, and relations and can be partial, but it does not disclose output format, scope limits, or whether the snapshot represents a point-in-time state. No contradiction with annotations.

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

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

Two short sentences, front-loaded with the verb and object, with no filler. The partial-snapshot option is stated in one compact clause.

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 tool with two optional parameters and no output schema, the description names the returned concept (data model snapshot) and how to narrow it. It could mention the output shape or format explicitly, but everything needed to make a safe call 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% and both parameters already carry descriptions, including mutual exclusivity. The description merely restates the include/exclude choice without adding formats, defaults, or side effects, so it stays at the 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 clear verb and object: read a snapshot of the full data model (collections, fields, relations). The parenthetical scope differentiates it from siblings like get_collection_schema for a single collection or list_collections for only collection names.

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

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

The description gives no guidance on when to choose this tool over schema-related siblings such as get_collection_schema or diff_schema. The only usage hint is parameter-level ('Pass include_collections or exclude_collections'), which explains filtering options, not tool-selection criteria.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to restate safety. It adds no behavioral details beyond the schema (e.g., not-found behavior, permission requirements, field projection effects), but it also does not contradict the annotations.

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

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

The description is a single front-loaded sentence with no filler: verb, resource, and lookup key in that order. Every word contributes.

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-by-ID tool with a fully described parameter schema and readOnlyHint, the description is nearly complete. It would be stronger if it named get_users as the alternative for unbounded listing, but nothing required for a correct first 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%, so the description need not document parameters. The 'by ID' phrasing adds no semantics beyond the required id property, and the optional fields array is not mentioned in the description.

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

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

The description names a specific verb ('Get'), a clear resource ('a specific user'), and the selection key ('by ID'). It is immediately distinguishable from the sibling list tool get_users.

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 'specific user by ID' implies this is the single-record companion to get_users, but the description never explicitly states when to choose this tool over get_users or how to handle a missing ID. Usage context must be inferred from the name and schema 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?

Annotations already declare readOnlyHint=true, so the safe read-only nature is covered. The description adds the behavioral context of returning all users and supporting optional filtering and pagination, but it does not disclose details such as default ordering, response shape, or pagination limits beyond what the schema already provides. No contradictions with annotations.

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

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

The description is a single concise sentence that front-loads the core action ('Get all users') and summarizes the key capabilities. There is no filler, repetition, or unnecessary detail, making it easy for an agent to parse quickly.

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

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

For a read-only list tool with no output schema, the description gives the essential purpose but leaves out some operational details, such as how the filter object is structured, what fields are sortable, and how search behaves. The schema covers parameter names but not richer semantic context. It is adequate for basic selection but not fully complete for confident invocation in all 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%, and each parameter has a basic description such as 'Sort fields' and 'Number of users to return (default: 25)'. The tool description itself adds no parameter-level meaning beyond what the schema already supplies. A baseline of 3 is appropriate since the schema carries the parameter documentation burden.

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

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

The description uses a specific verb and resource: 'Get all users', which clearly identifies a listing operation. It also distinguishes itself from the singular sibling get_user by explicitly stating 'all users'. The mention of optional filtering and pagination further sharpens the scope.

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 this tool is the appropriate choice for retrieving multiple users, especially with filter/pagination needs. However, it does not explicitly state when to use get_users versus get_user, nor does it mention any alternatives or exclusions. Usage context is only implied, not directly stated.

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

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

Annotations already mark this as destructive (destructiveHint: true), and the description adds useful operational context such as the 50mb file size limit and the exact batch file structure. It does not, however, describe what destruction occurs beyond the schema's `dangerously_allow_delete` and `confirm` parameters, so the added behavioral context is moderate.

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

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

The description is front-loaded with the core purpose, followed by compact mode-specific guidance and a helpful batch file example. Every sentence contributes meaningful information with no filler or repetition.

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 description covers the two main call patterns, file format expectations, version requirements, and file size limits. Since there is no output schema, explaining the response is not explicitly required, and the provided detail is sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces the key `collection` omission rule and gives a concrete batch example, but it does not add substantial new semantics beyond what the parameter descriptions already state.

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

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

The description opens with a specific verb and resource: import rows from a CSV or JSON file into a collection or multiple related collections. It clearly distinguishes this tool from item-level siblings like create_item by emphasizing file-based, potentially multi-collection imports.

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

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

The description explicitly explains the two usage modes: pass `collection` for single-collection imports, or omit it for batch multi-collection imports. It also provides format requirements and a Directus version constraint, giving clear contextual guidance, though it does not name alternatives like bulk_operations.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=true, so the safety profile is covered. However, the description adds no behavioral context beyond the basic operation; it does not clarify whether system collections are excluded by default, how results are returned, or any other runtime behavior.

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 filler words. Every part of it contributes meaning: the action, the resource, and the scope. It is appropriately concise for a simple list operation.

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 list tool, the description is mostly adequate, but it leaves some gaps. There is no output schema, so the return shape is not described, and the optional include_system behavior is only implied by the parameter schema rather than integrated into the tool description.

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 single parameter include_system has 100% schema description coverage, so the schema explains it. The description does not add extra parameter context, but the baseline of 3 is appropriate since the schema already carries the semantic weight.

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

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

The description uses the specific verb 'List' with the resource 'collections' and scopes it to the Directus instance. It clearly contrasts with sibling tools like get_collection_schema or create_collection, which operate on individual collections rather than enumerating all of them.

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

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

The description implies this tool is for enumerating collections, but it does not explicitly state when to prefer it over siblings such as get_collection_schema or analyze_collection_schema. There are no exclusions or alternative suggestions, leaving the usage context mostly to inference.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description does not contradict them. It adds 'verify access' as extra context, but does not explain side effects, whether the refresh is global or per-collection, or what happens to the cache.

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, compact sentence with no filler. The core action is front-loaded and the secondary verification is stated directly.

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 description is adequate for a simple one-parameter operation, but it leaves ambiguity: omitting the optional collection might mean refreshing all collections, and 'verify access' is not elaborated. Annotations cover the safety profile, but these behavioral details are 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%, and the sole parameter 'collection' already has a description in the input schema. The tool description adds no further semantic detail 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?

The description states a specific action ('Refresh Directus collection cache') and a secondary verification behavior ('verify access'). It clearly identifies the resource and is distinguishable from all sibling tools, none of which mention cache refresh.

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 is given on when to use this tool versus alternatives, such as after schema changes or before read operations. There are no exclusions or conditions to help an agent decide between this and the many sibling tools.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description is consistent with them. It adds useful behavioral context by specifying that search is scoped to 'this server' and that the result is full tool definitions ready for direct invocation.

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

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

Two short sentences with no filler. The primary action is front-loaded, and the usage guidance is delivered in a single clear clause.

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

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

For a simple two-parameter search tool, the description plus fully documented schema and safety annotations are sufficient. It tells the agent when to use it, what it searches, and what it returns.

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 query and limit are already fully documented. The description only restates the query concept as a 'task description' and adds no additional semantic 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?

The description uses a specific verb ('Find') and resource ('tools on this server'), and states the output ('return their full definitions so they can be called directly'). It also positions itself as the meta-search entry point, distinguishing it from sibling tools that perform individual operations like update_item or delete_field.

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

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

The description gives an explicit usage directive: 'Use this first when unsure which tool to use.' This is clear context for when to invoke it, though it does not list when-not-to-use cases or name specific 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?

The annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds no behavioral context beyond these. It does not warn about side effects, potential data modifications, asynchronous execution, or whether triggering a flow can have irreversible consequences.

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

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

The description is a single, short sentence that communicates the basic purpose without unnecessary words. It is front-loaded and easy to parse, though it sacrifices explanatory value 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?

Given that this tool has a destructive hint, a nested data parameter, and no output schema, the description is too sparse. It does not explain return behavior, side effects, or how to construct meaningful data for the flow, leaving significant gaps for an agent deciding whether and how to invoke it.

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

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

The schema description coverage is 100%, so parameters are fully documented in the schema itself. The description adds no further detail about how data should be structured for the flow, but the schema alone provides adequate parameter-level meaning for this 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?

The description clearly states the action ('trigger') and the resource ('a flow execution'), which is enough to convey the core purpose. It is distinguishable from sibling tools like get_flows, create_flow, or update_flow because it focuses on triggering execution rather than managing flow definitions.

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 is provided about when to use this tool versus alternatives such as get_flows, create_flow, or bulk_operations. The description does not mention prerequisites, expected context, or any conditions under which manual triggering is appropriate.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the safety profile is covered without description restatement. The description adds only the 'existing field' and 'collection' scope, but does not explain what updating may affect or whether field type changes can destroy data. This is acceptable given the annotations, but no extra behavioral depth is added.

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 short sentence that front-loads the verb and resource. Every word earns its place, and there is no redundant phrasing or filler. It is concise without being vague at the purpose level.

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 10-parameter mutation tool with nested objects and no output schema, the one-line description is minimal. However, the rich parameter schema and annotations compensate for much of the missing context, making the tool minimally usable. It still lacks guidance on partial update semantics, destructive side effects of changing field types, and relationship to create_field/delete_field.

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?

All 10 parameters have descriptions in the input schema, so schema coverage is 100%. The description itself adds no parameter-level meaning, so the baseline of 3 applies. An agent must rely on the schema for details about collection, field, type, unique, required, interface, options, validation, default_value, and note.

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 and resource: 'Update an existing field in a collection'. The word 'existing' distinguishes it from create_field, and 'field' clearly separates it from update_item and collection-level operations. It does not explicitly name sibling alternatives, but the operation and resource are clear enough.

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, and no alternatives such as create_field or update_item are mentioned. The only implicit hint is that the field must already exist. An agent must infer selection criteria from the tool name and sibling list rather than from deliberate guidance.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, but the description adds no behavioral context such as whether omitted fields are preserved or overwritten. It does not contradict the annotations, but it contributes nothing beyond what the structured metadata already conveys.

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 filler or redundancy. It is concise and well-structured, although it is very thin on substantive 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 output schema, the description leaves key context unexplained: whether data is a partial or full replacement, what happens to omitted fields, and what response the agent can expect. The schema and annotations carry most of the weight, but the description is too thin to be 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 schema fully documents id and data, including each updatable field. The description adds no parameter-level meaning, but the baseline of 3 applies when the schema carries the full parameter documentation burden.

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

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

The description clearly states the action and resource: 'Update an existing flow'. It is distinguishable from siblings like create_flow, delete_flow, and trigger_flow through the verb 'update' and the word 'existing', though it never explicitly names those alternatives.

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

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

No guidance is given about when to use this tool versus create_flow, delete_flow, trigger_flow, or update_item. The description only restates the tool's basic purpose and leaves all selection decisions to inference.

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

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

Annotations already show destructiveHint=true and idempotentHint=true, and the description adds useful versioning behavior: published items in versioned collections are read-only and a draft version must be targeted. This goes beyond the raw annotations without contradicting them.

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 concise sentences. The main purpose is front-loaded, and the important versioning caveat follows immediately. Every sentence adds relevant information 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?

The description covers the key behavioral exception (versioned collections) and all parameters are documented in the schema. It is complete enough for typical use, though it could be more explicit about whether 'data' represents a partial update or a full replacement. Given the moderate complexity and annotation coverage, this is a minor gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's versioning guidance overlaps with the version parameter's existing schema description rather than adding meaningful new parameter-level semantics. It clarifies the versioning context but does not add much 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 clearly states the operation: 'Update an existing item in a collection.' The verb 'Update' plus the resource 'existing item in a collection' precisely distinguishes this from sibling tools like create_item and delete_items. The versioning caveat further clarifies the scope.

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 clear situational guidance for versioned collections: published items are read-only, so target a draft version instead. It does not explicitly name alternative tools, but the update-vs-create distinction is implicit in 'existing item' and the versioning instruction is actionable.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds the validation scope but does not disclose behavioral details such as retry/wait semantics (implied by waitTime), error behavior, or what 'properly accessible' checks.

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, tightly worded sentence that communicates the tool's purpose without any filler. The key scoping phrase ('newly created collection') is front-loaded.

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

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

For a simple validation tool with two parameters and strong annotations, the description is complete enough for invocation. It could be improved by stating what the return value or success/failure signal looks like, but that is not essential given the tool's simplicity.

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 parameters already documented in the input schema. The description adds no additional parameter-level meaning beyond what the schema provides, 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 names a specific verb ('Validate'), a specific resource ('newly created collection'), and a concrete success criterion ('properly accessible'). This clearly distinguishes it from sibling tools like validate_collection_schema or diagnose_collection_access.

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

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

The description clearly implies the tool is used immediately after collection creation to confirm accessibility. However, it does not explicitly exclude alternatives or state when to choose this tool over validate_collection_schema or diagnose_collection_access.

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

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

Annotations already declare readOnlyHint=true, and the description adds no behavioral context beyond the generic verb 'Validate.' It does not explain what the validation checks, how strict mode changes behavior, whether it returns a report or throws errors, or what side effects (if any) could occur. The description does not contradict the annotations, but it also does not enrich them.

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 compact sentence with no filler words. The main action and target are front-loaded, and the additional 'and relationships' scope is expressed efficiently without redundancy.

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

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

For a tool with no output schema, the description is incomplete: it does not explain what a validation result looks like, how strict affects the outcome, or what kinds of schema/relationship problems are detected. The sibling context shows many related analysis and validation tools, but this description gives no hints about its specific niche or 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%, so the input schema already explains both parameters: 'collection' is a collection name and 'strict' enables strict validation. The description's reference to 'relationships' adds a small amount of scope context, but it does not meaningfully deepen understanding of either parameter's semantics.

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

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

The description uses a specific verb ('Validate') and names the resource ('collection schema and relationships'), making the tool's core purpose clear. However, it does not distinguish this tool from closely related siblings such as analyze_collection_schema, analyze_relationships, or validate_collection_creation, so an agent could struggle to pick the right one based on the description alone.

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

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

The description provides no guidance on when to use this tool versus alternatives like analyze_collection_schema or validate_collection_creation. There are no conditions, exclusions, or hints about which scenarios call for this specific validation tool rather than another sibling.

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