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

Annotations already mark the call as a non-read mutation; the description adds genuinely useful behavior beyond that: ids are applied in order, and already-assigned or unknown ids yield a partial status via failed[] instead of failing the whole call. This clarifies failure semantics that neither the annotations nor the schema convey.

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

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

Two purposeful sentences with the operation warning front-loaded, followed by the action and the most important edge-case behavior. There is no filler or repetition of schema material.

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 note about failed[] and status=partial is helpful, but with no output schema the description still does not explain the success response shape or overall return contract. For a mutating tool with six parameters, that leaves an agent needing to infer the rest of the response behavior.

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

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

Schema coverage is 50%, and the description adds meaning for element_type, fact_table_id, and element_ids by naming the element kinds and stating that ids are applied in order. However, it leaves the project_id/version_id scoping and the exact form of element_ids ambiguous, so compensation for the schema gap is only partial.

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 ('Attach'), a precise resource ('existing measures, dimensions, facts or dimension groups to a fact table'), and the leading 'WRITES TO DATAFORGE' signals a mutating operation. This separates it clearly from read-only siblings and from df_unassign_from_fact_table without needing to inspect schemas.

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 'Attach existing...' establishes the intended context: this is for linking already-created elements to a fact table, which implicitly distinguishes it from the df_write_* creators and the df_unassign sibling. It does not explicitly name alternatives or exclusions, so it stops short of a 5.

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

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

With annotations that only set readOnly/idempotent/destructive to false, the description carries the burden of explaining side effects. It states create/update but does not disclose update semantics, partial-failure behavior, permissions, or what happens to existing fields when updating. For a write operation, too little is revealed beyond the action itself.

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 text is short and not padded, but the opening sentence 'WRITES TO DATAFORGE' is redundant filler that does not earn its place. The useful content is compact but under-structured: there is no front-loaded rationale, no alternatives, and no behavioral context.

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

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

For a complex bulk write with a large dimensions array, no output schema, and sparse annotations, a two-sentence description is inadequate. Missing guidance on how updates are keyed, how errors or partial writes behave, and when to choose this tool over related siblings leaves an agent to infer too much.

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 about 75% and the input schema already documents project_id, version_id, idempotency_key, and the connected_source object in some detail. The description adds nothing about parameter meaning, so it is at baseline: not harmful, but no added value over 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 second sentence states a concrete operation—'Create and/or update many dimensions in one call'—with a clear resource and batch scope, distinguishing it from the singular df_write_dimension. However, the first sentence 'WRITES TO DATAFORGE' is generic and does not add operational clarity, so it falls just short of a top-tier purpose statement.

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 'many dimensions in one call' implies the batch-use case, so an agent can infer this is for bulk create/update rather than single writes. But the description never explicitly says when to prefer it over df_write_dimension or how it differs from other bulk write tools like df_bulk_write_measures, and it gives no exclusions or naming of 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 convey that this is a non-read-only, non-idempotent, non-destructive operation, and the description adds little beyond that. It does not disclose partial-failure behavior, atomicity, validation, or any side effects beyond the obvious write. The idempotency_key parameter in the schema covers replay behavior, but the description itself offers no additional behavioral context.

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

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

The description is only two sentences and avoids extraneous detail, making it easy to scan. The opening 'WRITES TO DATAFORGE' is somewhat redundant given the tool name and the uppercase styling, but the second sentence economically states the core behavior.

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

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

There is no output schema, so the description should compensate by explaining expected responses, error modes, or partial-failure semantics, but it does not. For a complex bulk mutation tool, this leaves the agent without enough context to handle results or failures 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?

Top-level schema coverage is 75%, and nested fact properties are individually described, so the schema carries most parameter semantics. The description adds only that multiple facts can be passed at once, which is already visible from the 'facts' array type and minItems. No extra meaning is added for project_id, version_id, or idempotency_key beyond what their 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 states a clear action ('Create and/or update') on a specific resource ('facts') with an explicit scope ('many facts in one call'). This distinguishes it from the sibling df_write_fact (single fact) and other bulk operations on different entities like measures or dimensions.

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 'many facts in one call' implies the tool is for batch operations, but it never names alternatives such as df_write_fact for a single fact or explains when not to use it. There is no explicit when/when-not guidance or mention of related bulk-write siblings like df_bulk_write_measures.

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

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

Beyond the annotations, the description reveals meaningful behavioral details: items are applied in order, each in its own transaction, and partial failures return status=partial with a failed[] array indexed by row. This is valuable operational context that an agent needs to interpret results correctly.

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

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

Three short sentences with no filler. The mutation warning is front-loaded, the core behavior follows, and the failure semantics close the description efficiently. Every sentence earns its place.

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

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

For a write operation with no output schema, the description does well to explain partial-failure behavior and per-item transactions. It could go further by describing the full success response shape, but the combination of schema descriptions and this behavioral summary gives an agent enough to invoke and interpret the call.

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 already high at 75%, so the baseline is 3. The description adds important semantic meaning by explaining that an item with `id` is updated and one without is created, plus ordering and transaction semantics that affect how the measures array is processed.

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/or update many measures in one call.' This clearly identifies the resource (measures) and scope (bulk), distinguishing it from siblings like df_write_measure (single measure) and df_bulk_write_dimensions/facts (different resource).

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

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

The description communicates that this is the bulk path for creating/updating measures, which implies use when multiple measures need writing at once. It does not explicitly name alternatives like df_write_measure or state when not to use it, but the 'many measures in one call' wording provides clear context.

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

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

Annotations already indicate idempotent and non-destructive behavior. The description adds value by clarifying that it is a dry run that writes nothing, and by disclosing the exact output shape (valid, errors[], warnings[], element counts). It also implies network/credential usage implicitly through the authentication parameter, but that is not explicit. It does not contradict annotations; readOnlyHint false is consistent with it being a validation that may read external sources without writing. The extra context on return fields goes beyond what annotations provide.

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

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

The description is a single, efficient sentence that front-loads the most critical information ('Dry run') and immediately communicates the key behavior (validate, no writes) and output. There is zero redundancy; every word earns its place. It is concise without sacrificing clarity.

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

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

Given the tool's complexity (11 parameters, nested authentication object, two source types), the description is far too brief. It does not explain how to specify the source (git vs file), which parameters are required for each source_type, how authentication is configured, or what 'element counts' refers to. There is no output schema, so the description's brief return list is helpful but insufficient for an agent to correctly assemble the many optional parameters. The tool clearly needs more operational context to be used 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 only 36%, with 7 of 11 parameters lacking any description. The tool description does not explain any parameter semantics, such as how to specify git vs file source, which parameters are required for each source_type, or how authentication is used. The description only mentions 'import source' generically without mapping to the schema. With low schema coverage, the description should compensate but does not, leaving the agent without sufficient guidance to fill in the many undocumented parameters.

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

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

The description clearly states the tool's purpose: it is a dry-run validation of an import source, explicitly saying it writes nothing. It names the resource ('import source') and the action ('validate'), and the return structure (valid, errors, warnings, element counts) distinguishes it from import tools like df_import_version_from_git and preview tools like df_preview_import. The verb is specific and the scope is unambiguous.

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

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

There is no guidance on when to use this tool versus alternatives. It does not mention that it is a pre-flight check before an actual import, nor does it contrast with df_preview_import or the import tools. The description implies a validation role, but it never explicitly says 'use this before importing' or names alternative conditions. An agent has to infer usage from the tool name and siblings.

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

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

Annotations are minimal (readOnlyHint=false, idempotentHint=false, destructiveHint=false) and do not describe side effects. The description adds meaningful behavioral context: it states the operation writes to DataForge, requires an admin API key, and that credentials are encrypted and never returned. This discloses permission and security behavior beyond the annotations.

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

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

The description is three short sentences with zero filler. The most important signal ('WRITES TO DATAFORGE') is front-loaded, followed by the tool's purpose, permission requirement, and credential security. Every sentence earns its place.

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

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

For a complex 8-parameter operation with nested objects and no output schema, the description covers the essentials (purpose, permissions, credential handling) but leaves gaps: it doesn't mention settings behavior, idempotency key usage, or what happens on duplicate names. The schema partially covers authentication and idempotency, but the description doesn't integrate these details. It is minimally viable but not comprehensive.

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

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

Schema description coverage is only 25%, leaving most of the 8 parameters undocumented. The description itself does not explain any parameters (e.g., name, platform, repository_url, branch, authentication), and it does not compensate for the low schema coverage. The only parameter-related context comes from inline schema descriptions for authentication and idempotency_key, not from the tool 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 states a specific verb and resource: 'Register a Git connection for the company.' The leading 'WRITES TO DATAFORGE' clarifies this is a write operation, and the verb 'register' clearly indicates creation, distinguishing it from sibling tools like df_update_git_connection or df_delete_git_connection. The purpose is immediately unambiguous.

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

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

The description provides a clear usage context: registering a Git connection for the company, plus a prerequisite ('Requires a company administrator API key'). It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to know when to invoke this tool versus read-only or update/delete siblings.

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

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

Annotations already indicate a non-read-only, non-idempotent, non-destructive operation. The description adds useful context that it writes to DataForge and that an initial version is automatically created. It does not disclose permissions, reversibility, or other side effects, but it goes slightly beyond the annotations.

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

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

The description is three short sentences with no filler and the write warning is front-loaded. It is sparse but not padded, and every sentence carries at least some information.

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

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

For a mutation tool with no output schema and minimal annotation detail, the description covers the key side effect (initial version creation) but omits expected response, prerequisites, and reversibility. It is minimally viable for a straightforward create operation, but not 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 50%: color and idempotency_key are documented, but name and description are not. The tool description adds no parameter-level meaning and does not compensate for the undocumented parameters or explain the idempotency_key behavior.

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 the specific verb and resource: 'Create a project.' The added note that an initial version is created clarifies scope. It does not explicitly distinguish this from siblings like df_create_version or df_update_project, but the resource is 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?

There is no guidance on when to use this tool versus alternatives such as df_create_version or df_import_version_from_git. The description only restates the core action without context, triggers, or exclusions.

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

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

Annotations only say readOnlyHint=false, so the description's 'WRITES TO DATAFORGE' mainly restates that, but it adds meaningful behavioral facts: content is cloned from the stated source and creation consumes the license version limit. There is no contradiction with 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 two short sentences and front-loads the mutation warning before the purpose. The only mildly redundant element is 'WRITES TO DATAFORGE,' which adds little beyond the readOnlyHint=false annotation.

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?

It captures the two behavioral essentials (clone source and license count), but with no output schema it does not describe what a successful call returns. It also leaves is_global and the exact semantics of project_id/name to inference, which is a noticeable gap for a create endpoint.

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

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

Schema description coverage is only 20%, and the description compensates only for clone_from_version by explaining the clone source and global-version default. Required params like project_id and name, plus is_global, receive no semantic help, leaving them ambiguous beyond the property names.

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 by declaring a write operation and then says 'Create a project version,' a specific verb and resource. This clearly positions it against siblings like df_update_version and df_delete_version, so an agent can identify it without opening the schema.

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

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

It explains the clone default ('from the current global version when omitted'), which helps decide whether to pass clone_from_version, but it never says when to prefer this tool over df_update_version, df_import_version_from_git, or df_export_version_to_git. Usage context is only implied by the word 'Create.'

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

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

Annotations already mark this as destructive and non-read-only, but the description adds meaningful context: deletion is permanent, and it is rejected under specific dependency conditions. This goes beyond what the annotations state and helps the agent anticipate failure cases.

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

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

The description is short and front-loaded with a clear permanent-deletion warning. The first sentences are slightly redundant with the tool's name, but every sentence conveys useful operational information. No filler is present.

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

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

For a simple three-parameter delete operation with destructive annotations and no output schema, the description provides the essential context: what is deleted, that it is permanent, and the conditions that cause rejection. It does not mention alternative tools for resolving dependencies, but the core invocation conditions are sufficiently covered.

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?

project_id and version_id already have schema descriptions, and the description makes clear that dimension_id is the dimension being deleted. However, dimension_id itself remains undocumented in the schema and the description adds no further detail about formats, types, or how IDs relate. Schema coverage is adequate but not complete.

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 the specific action ('Delete a dimension') and resource, and the resource name clearly separates it from sibling tools like df_delete_measure, df_delete_fact, and df_delete_dimension_group. The warning that deletion is permanent is unambiguous, so an agent knows exactly what this 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 usage: call this tool when a dimension should be deleted. It gives a rejection condition (belongs to a dimension group or referenced by a formula) but does not explicitly direct the agent to alternatives such as df_remove_group_dimension or df_delete_dimension_group. Usage context is present but not fully explicit.

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

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

The description goes beyond annotations by disclosing the permanent nature of the deletion (destructiveHint only says destructive, not permanent) and the specific rejection condition when assigned to a fact table. This adds valuable context that annotations do not capture. Idempotency is annotated but not described, which is acceptable.

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

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

The description is two sentences with the critical warning front-loaded and no unnecessary words. It is efficient and well-structured for quick comprehension.

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 essential aspects: permanent deletion and the assignment constraint. It does not mention return values or error handling, but for a delete operation without an output schema, that is often implicit. It is reasonably complete for an agent to call correctly.

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

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

Schema coverage is 67% with descriptions for project_id and version_id, but dimension_group_id lacks a description. The tool description adds no parameter details, so it does not compensate for the missing schema description. However, the parameter is self-explanatory from its name, and the schema covers most parameters, making this a moderate gap.

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 'Delete' and resource 'dimension group', distinguishing it from sibling tools like df_delete_measure and df_delete_dimension. It also adds permanent-deletion scope and a rejection condition when assigned to a fact table, making the purpose unambiguous.

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

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

The description provides the key context that the operation is permanent and is rejected while the group is assigned to a fact table, implying a prerequisite to unassign first. However, it does not explicitly name alternative tools or state when to use this over other delete operations, though the name itself is sufficiently specific.

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 include destructiveHint=true and readOnlyHint=false. The description adds a redundant emphasis on permanent deletion but does not disclose additional behavioral details such as idempotency behavior, cascading effects, or required permissions. It 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 extremely concise and front-loads the destructive warning. Every word earns its place, though the first sentence is broad and partially redundant with the second.

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

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

For a destructive operation with three required parameters and no output schema, the description is too sparse. It does not explain scoping, what happens on deletion, or how to ensure the correct project/version/fact context, relying heavily on the schema and tool name.

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

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

Schema description coverage is 67% (fact_id is not described), which is below the high-coverage threshold. The description does not compensate by explaining what each parameter means or how project_id, version_id, and fact_id relate, so the agent must infer the semantics of the key 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 ('Delete a fact') and clearly distinguishes this tool from sibling delete tools such as df_delete_relationship, df_delete_version, and df_delete_measure. The explicit permanence warning also helps the agent understand the operation's weight.

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 df_delete_fact versus alternative tools. It does not mention prerequisites, exclusions, or conditions that would select this tool over its many delete siblings, leaving the agent to infer usage from the name and 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 indicate destructiveHint=true and readOnlyHint=false. The description adds value by stating 'PERMANENTLY DELETES DATA IN DATAFORGE' (reinforcing irreversibility) and the rejection condition for active relationships, which is not covered by annotations. 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 extremely concise (two sentences) and front-loads the most important warning about permanent deletion. Every word earns its place, with no redundancy or irrelevant details.

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

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

For a destructive operation with no output schema, the description provides essential context: the permanence, the rejection condition, and the resource type. It does not explain the full impact on related data (beyond the relationship rejection), but this is sufficiently implied. The required parameters are straightforward, and annotations cover safety. The description is adequate 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 67% (project_id and version_id are described, fact_table_id is not). The description adds no parameter-specific information, but fact_table_id is self-explanatory given the tool name. Since coverage is moderate and the missing parameter is obvious, a 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 states a specific verb and resource ('Delete a fact table') and emphasizes the permanent destructive nature, clearly distinguishing it from sibling tools like df_delete_fact (which deletes individual facts) and df_delete_relationship. The agent can immediately identify the target action.

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

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

The description provides a critical usage constraint ('Rejected while it has active relationships'), telling the agent when the operation will fail. However, it does not explicitly name alternative tools or state when to use this vs. deleting individual facts or relationships. The guidance is present but not fully explicit about 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 and readOnlyHint=false, and the description reinforces this with 'PERMANENTLY DELETES DATA IN DATAFORGE.' It adds the important context that the deletion is permanent and identifies what gets destroyed (a saved Git connection). No contradiction with annotations is present.

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

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

The description is short and front-loaded with the destructive warning, followed by the precise action. The first sentence is somewhat redundant with the destructiveHint annotation and slightly broad, but the overall length is appropriate and every sentence serves a 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?

For a one-parameter destructive operation, the description sufficiently tells the agent what the tool does, what resource is affected, and that the effect is permanent. It does not describe response behavior or prerequisites, but the operation is simple and no output schema exists, so this is acceptable.

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 only defines connection_id as an integer, and the description does not explicitly explain it. However, the phrase 'saved Git connection' gives enough context to infer that connection_id identifies which connection to delete. With a single obvious parameter, the gap is minor, but the description adds little direct parameter meaning.

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

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

The description states a specific verb and resource: 'Delete a saved Git connection.' The caps-lock warning is broad, but the second sentence disambiguates it clearly. This distinguishes it from other delete tools and from Git connection tools like df_update_git_connection or df_test_git_connection.

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 communicates when to use the tool: when a saved Git connection needs to be deleted. It does not explicitly mention alternatives or exclusions, such as using df_update_git_connection for edits or df_test_git_connection for validation, so it stops short of full routing guidance.

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

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

Annotations already mark the operation as destructive. The description adds valuable behavior beyond that: the deletion is permanent and will be rejected with a conflict if another element's formula references the measure. This is useful disclosure.

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

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

The description is short and the key warning is front-loaded. The all-caps sentence is somewhat redundant with destructiveHint, but the conflict-rejection detail 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 simple delete operation, the description covers what is deleted, the destructive nature, and an important failure mode. It does not explain return values or prerequisites, but with no output schema these are less critical.

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

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

The schema describes project_id and version_id, covering 67% of parameters. The description adds no parameter-specific detail, and measure_id remains undocumented, but its meaning is evident from the tool name and the 'Delete a measure' sentence.

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 the specific resource ('measure') with a clear action ('Delete') and adds the critical constraint 'PERMANENTLY DELETES DATA.' This differentiates df_delete_measure from sibling delete tools like df_delete_dimension and df_delete_fact.

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

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

Usage is implied by the action and resource: use this tool to delete a measure. However, there is no explicit when-to-use guidance or contrast with sibling delete tools, so an agent must infer context from the tool name.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is structured. The description adds critical context beyond annotations: the deletion is permanent, cascades to all versions and their entire content, and cannot be undone. This is exactly the kind of behavioral disclosure that helps an agent warn users or avoid accidental data loss. It does not contradict annotations; idempotentHint=true is consistent with a delete operation that succeeds even if the project is already gone.

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

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

Three sentences, all high-value. The warning is front-loaded ('PERMANENTLY DELETES DATA'), the scope is explicit, and the irreversibility is stated. No filler or repetition of schema details.

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

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

For a single-parameter destructive tool with no output schema, the description covers the essential context: what is deleted, the cascade scope, and irreversibility. It does not mention authorization requirements (e.g., needing project access) or what the response looks like, but those are less critical for a delete operation and the annotations already cover the safety profile.

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

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

Schema description coverage is 0%, so the description must compensate. It names the key parameter (project_id) implicitly by saying 'Delete a project', but it does not explain the format, type, or how to obtain the project_id. However, with only one required parameter named project_id, the schema already provides the parameter name and type, and the description's scope clarification adds enough meaning for an agent to understand what the parameter refers to.

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 ('deletes'), a specific resource ('project'), and the full scope ('WITH ALL OF ITS VERSIONS and their entire content'). It clearly distinguishes this from sibling tools like df_delete_version and df_delete_relationship by emphasizing the project-level cascade.

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 clear this is the tool for deleting an entire project and everything under it, which implicitly distinguishes it from df_delete_version (delete a single version) and df_delete_relationship (delete a relationship). It does not explicitly name alternatives or state when not to use it, but the destructive scope is unambiguous enough for an agent to select it correctly.

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

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

Annotations already mark destructiveHint=true and idempotentHint=true. The description adds the explicit 'PERMANENTLY DELETES DATA' warning, which reinforces irreversibility, but it provides no detail about cascading effects or whether any confirmation is needed.

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

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

The description is two short sentences and contains no filler. The permanence warning is front-loaded and directly supports safe usage.

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 three-parameter delete operation, the annotations and description convey the essential destructive nature. Yet the absence of usage guidance and any mention of preconditions or post-conditions leaves the context only partially 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?

With 67% schema coverage, project_id and version_id are documented, and 'Delete a relationship' makes the role of relationship_id clear. However, the description adds no real semantic value beyond the schema and does not compensate for relationship_id's missing schema 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 states a specific verb and resource: 'Delete a relationship.' The all-caps warning clarifies this is a permanent deletion, and naming 'relationship' distinguishes it from sibling delete tools such as df_delete_version or df_delete_measure.

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. It does not mention verifying the relationship first with df_get_relationship, nor does it distinguish deletion from creation/listing 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 mark the tool as destructive and non-read-only. The description adds the important 'permanently' qualifier, emphasizing irreversibility and that DataForge data is affected. It does not mention idempotency, but the annotations already cover that aspect.

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 very short and front-loads an irreversible-deletion warning before the actual purpose. The all-caps sentence is somewhat redundant with the destructive annotation, but there is no filler or restatement of the tool name.

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

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

For a simple delete operation, the required fields and annotations provide most of the invocation context. However, the description does not explain what a verification filter is, what happens after deletion, or the role of the optional fact_table_id, leaving small but real knowledge 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 descriptions cover only project_id and version_id; filter_id and fact_table_id are undocumented. The description does not clarify that filter_id identifies the verification filter or explain the role of the optional fact_table_id. With 50% schema coverage, this is insufficient compensation.

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 is deleting a verification filter, a specific resource with an identifiable verb. It is not a tautology and the resource is distinct from other delete tools. It does not explicitly contrast itself with sibling delete operations, so it stops short of a top score.

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

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

The description provides no guidance about when to use this tool versus alternatives, such as df_write_verification_filter for creating/updating filters or df_delete_version for broader deletions. The destructive warning implies caution but does not state a concrete usage condition.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, and the description reinforces this with 'PERMANENTLY DELETES DATA.' It adds genuinely useful behavioral context beyond the annotations: deleting a version cascades to 'all of its content' and the current global version is protected. No contradiction with annotations.

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

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

The description is two sentences with no filler. The destructive warning is front-loaded, the action and scope are stated immediately, and the constraint about the current global version is the only additional necessary context.

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 two-parameter operation with no output schema, the description covers the action, the full impact, and the key edge-case restriction. The annotations handle the read-only/destructive profile, and nothing essential is missing for an agent to invoke this 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?

The schema covers both parameters at 100% with clear descriptions ('DataForge project id' and 'Project version id'). The description adds no additional parameter-level semantics, so it appropriately relies on the schema. Baseline 3 is correct.

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

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

The description opens with 'PERMANENTLY DELETES DATA IN DATAFORGE' and then specifies 'Delete a version and all of its content,' clearly identifying the resource (version) and the full scope of the deletion. It distinguishes this from the many sibling delete tools (df_delete_project, df_delete_relationship, df_delete_measure, etc.) by naming 'version' as the target.

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

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

The description implies usage by naming the action and target, and it provides one important when-not condition ('The current global version cannot be deleted'). However, it offers no explicit guidance about when to choose this tool over the many sibling delete tools, nor does it name any alternative for handling the current global version.

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 only state that the tool is non-read-only, non-idempotent, and non-destructive. The description adds important side-effect context: it writes/stores an archive in DataForge while leaving the project data unchanged, and returns a signed download link. This goes beyond the annotation booleans, though it omits details such as link expiry or authentication requirements.

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

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

The description is two compact sentences with no filler. The side-effect warning is front-loaded, and the second sentence efficiently captures both the storage behavior and the output format. Every sentence contributes useful 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 tool has a nested options object with 11 undocumented properties and no output schema, yet the description only provides the output format and a side-effect note. The required parameters are clear, but an agent would still need to guess about option semantics and when to use this over related tools. The context is incomplete 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?

The schema gives minimal descriptions for project_id and version_id, but the tool description itself adds nothing about parameters. The options object and its 11 nested properties are entirely undocumented, leaving ambiguous fields like use_system_key, save_connection, and encryption_password unexplained. With schema coverage at about 67% and no descriptive compensation, the parameter guidance is inadequate.

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 and resource: 'Export a version to a .dfexport.zip archive and return a signed download link.' The archive format and download-link output clearly distinguish this from the git-export sibling and other DataForge tools. The note that nothing changes in DataForge further clarifies the tool's 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 the use case: exporting a version as a downloadable file archive. However, it does not explicitly state when to prefer this over df_export_version_to_git or other alternatives, nor does it provide any exclusions. An agent must infer the right choice from the '.dfexport.zip' format and 'signed download link' outcome.

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 a key behavioral trait: exporting an unchanged version creates no commit and returns commit_hash=null, which is not captured in annotations. It also repeats the write warning 'WRITES TO DATAFORGE,' which aligns with readOnlyHint=false. However, it does not detail authentication handling, rate limits, or failure modes, so the added value 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 four short sentences with no filler. The write warning is front-loaded, followed by the core purpose, then auth guidance, then a key behavioral note. Every sentence earns its place, and the structure is 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?

This is a complex tool with 10 parameters, nested objects, and no output schema. The description explains the purpose and one auth-related decision but omits return value details (beyond the null commit_hash case), the meaning of options, and the roles of repository_url, branch, and commit_message. An agent would need to inspect the schema heavily, and even then, some semantics remain unclear.

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

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

With schema description coverage at 40%, the description compensates partially by clarifying that connection_id refers to a saved Git connection and that it is an alternative to the authentication object. This adds meaning beyond the bare schema. Yet it does not explain other required parameters like repository_url, branch, commit_message, or the options object, leaving significant gaps for a low-coverage 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 verb 'Export' and the resource 'a version's configuration' with the destination 'to a Git repository.' It distinguishes this from sibling df_export_version_to_file by explicitly naming Git, and the phrase 'WRITES TO DATAFORGE' signals this is a mutating operation, consistent with the tool's write nature.

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 guidance on choosing between connection_id and authentication, which is helpful for parameter selection. However, it does not explicitly state when to use this tool versus alternatives like df_export_version_to_file, nor does it mention any exclusions or prerequisites. The usage context is implied but not explicit.

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

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

Annotations already mark this as readOnly, idempotent, and non-destructive, so the description adds value by disclosing the error-handling contract: failures return succeeded=false with validation_errors rather than throwing an error. This is beyond what the annotations provide and is useful for an agent planning calls. No contradiction with annotations.

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

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

The description is two sentences, with the primary purpose front-loaded and the secondary behavioral note concise. Every word earns its place; there is no redundancy or fluff.

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

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

The description covers the tool's core behavior and error handling but omits the success return value (presumably the SQL text) and any parameter semantics. With six parameters and no output schema, an agent needs more detail to call this correctly, though the safety annotations mitigate some risk.

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 description adds zero information about any of the six parameters. Schema coverage is only 50% (descriptions for offset, project_id, version_id), leaving data_mart_id, limit, and language unexplained in both schema and description. The description should compensate for this gap but does not.

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

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

The description states a specific verb ('Generate'), a precise resource ('the SQL query of a data mart'), and immediately clarifies that nothing is executed or stored. This distinguishes it from sibling tools that fetch or write data mart definitions, such as df_get_data_mart or df_get_data_mart_view, without needing to inspect their schemas.

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 generating SQL without side effects, but it never explicitly states when to use it instead of alternatives. It does not mention any conditions, exclusions, or comparable tools, leaving the agent to infer the intended use case from the behavior note.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds context that include_db_schema=true returns a 'full cached table/column schema', but it does not explain the cache mechanics or how use_cache interacts with this 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?

Two concise sentences front-load the core purpose and then provide the key optional behavior. There is no redundant or irrelevant 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?

This is a moderately complex tool with six parameters Alert: The description lacks clarity on language and use_cache, does not fully explain connection_id, and only partially describes the return shape. The absence of an output schema raises the burden on the description, which is not met.

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

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

With only 33% schema description coverage, the description needs to compensate. It adds meaning for include_db_schema, but language and use_cache remain unexplained, and connection_id is only implicitly defined. The return-field list is helpful but does not clarify the input parameters enough.

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

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

The description clearly states the tool retrieves a single connection and enumerates the key fields returned (host, port, database, schema, username). It does not explicitly differentiate from siblings like df_list_connections or df_get_connection_schema, but the singular 'one connection' 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?

There is no explicit guidance on when to use this tool versus alternatives. The only conditional guidance is the include_db_schema flag explanation, which addresses a parameter rather than tool selection; no exclusions or sibling comparisons are provided.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond the annotations by revealing that the schema is a cached snapshot from the last refresh rather than a live query, which affects how the agent should interpret results.

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 deliver the core purpose, the cached/non-live caveat, and the intended use case. No filler or redundant repetition of schema details.

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 schema lookup with annotations covering safety, the description provides enough to select and invoke the tool correctly, and it hints at the return contents (tables and columns). It is slightly incomplete on parameter semantics and does not describe the output shape, but the core use case is well covered.

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

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

Schema description coverage is only 40%; project_id and version_id are documented in the schema, but language and use_cache are not described anywhere, and connection_id is only implied by 'connection' in the description. The description does not compensate for the undocumented parameters or explain how caching relates to the use_cache 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 states a clear verb ('Get'), a specific resource ('cached schema of a connection'), and the content (tables and columns). It also distinguishes the tool's purpose from sibling tools like df_get_connection by emphasizing the schema/cached nature.

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 when to use this tool ('to pick valid table and column names for write operations') and what it is not ('not a live query'). It does not name an alternative sibling, but the usage context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it returns a single consolidated raw payload, but it does not disclose behaviors like cache usage, response size, or implications of include_sql.

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

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

A single sentence that front-loads the verb and resource, then enumerates the payload composition. Every phrase adds information and there is 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 adequately sketches the return payload, which matters because there is no output schema. However, it leaves optional parameters unexplained and does not clarify how the response map to the sibling tools, so it is minimally viable but with 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 description coverage is only 40%; only project_id and version_id have descriptions. The tool description does not compensate by explaining language, use_cache, or include_sql, leaving three parameters effectively undocumented in both schema and 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 and resource ('Get the full raw export of a project version') and enumerates the payload contents: RMD content plus dimension groups, fact tables, and relationships. This clearly distinguishes it from siblings like df_get_rmd, which would only provide the RMD content.

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

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

The description implies this is the consolidated alternative to more granular tools, but it never explicitly states when to use it versus df_get_rmd, df_list_fact_tables, or df_list_relationships. No when-not-to-use guidance or alternative routing is provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by stating exactly what is included in the returned data mart definition, which is valuable because there is no output 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 front-loaded sentence that immediately states the operation and scope, then lists the included components. There is no filler or 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 moderately complex retrieval tool with no output schema, the description provides a useful high-level inventory of the response contents. However, it omits guidance on the optional language and cache parameters, does not differentiate from get_data_mart_view, and lacks enough detail for an agent to fully predict the returned structure.

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

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

Schema description coverage is only 40%, and the description adds no parameter-level meaning. It does not clarify data_mart_id, language, or use_cache, and 'one data mart' only weakly maps to data_mart_id. The schema's existing descriptions for project_id and version_id carry most of the 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 a specific verb and resource ('Get one data mart in full') and enumerates the contents: source fact tables, selected measures, facts and dimensions with aggregation and filter settings. It is clear and self-contained, but it does not explicitly contrast with sibling tools like df_get_data_mart_view or df_list_data_marts.

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 alternatives such as df_list_data_marts or df_get_data_mart_view. The agent must infer from the name and the word 'full' that this is the detailed single-data-mart getter, which is not reliable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about what information is returned (staleness, last refresh, status), which is useful. However, it does not disclose potential behaviors like cache usage (use_cache parameter) or whether the call may trigger a refresh, though the annotations cover the core safety aspects.

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 that front-loads the core purpose and lists the key output attributes. Every word earns its place, and there is 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 read-only inspection tool with annotations covering safety, the description is mostly adequate. However, with no output schema and only 40% parameter coverage, the description could have clarified the meaning of data_mart_id, language, and use_cache, and how the returned 'status' and 'staleness' are represented. The lack of parameter semantics leaves some gaps for an agent deciding how 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 only 40%, with project_id and version_id described but data_mart_id, language, and use_cache lacking descriptions. The description does not add meaning for these parameters beyond the schema. The tool's purpose implies data_mart_id identifies the target, but the description does not explicitly explain the parameters or their roles, so it does not compensate for the coverage gap.

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') and resource ('physical view materialized for a data mart') and enumerates the attributes returned (existence, object type, database, status, staleness, last refresh). It is clear what the tool does, though it does not explicitly distinguish it from the sibling df_get_data_mart, which likely returns the data mart definition rather than its physical view.

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 a read-only inspection use case (checking physical view details), but it does not explicitly state when to use this tool versus df_get_data_mart or other sibling tools. No exclusions or alternative routing are provided, so the agent must infer usage from the name and description.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds value by disclosing exactly what the returned object contains (primary key, member dimensions, hierarchy levels, related fact tables), which is behavioral context beyond the annotations.

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

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

One compact sentence that front-loads the purpose and then lists the output components. There is no redundancy or filler, making it 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?

With no output schema and incomplete parameter schema coverage, the description should compensate more. It explains return contents well, but leaves language and use_cache semantics unexplained, and does not address potential error cases or prerequisites. Overall, an agent can call the tool correctly for the core use case, but there are meaningful gaps.

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

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

Schema description coverage is only 40%, and the description does not compensate. It does not explain the meaning of language, use_cache, or dimension_group_id beyond what is implied by the tool name. The two schema-described parameters (project_id, version_id) are straightforward, but the other three remain undocumented in both schema and 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 states a specific verb ('Get'), a specific resource ('one dimension group'), and enumerates its contents (primary key, member dimensions with hierarchy levels, related fact tables). This clearly differentiates it from siblings like df_list_dimension_groups, df_get_dimensions, and df_get_fact_table.

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 'Get one dimension group' makes it clear this is the tool to use when you have a specific dimension_group_id and need its details, as opposed to listing all groups. However, it does not explicitly name alternative tools or state when not to use it, so it earns a 4 rather than a 5.

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

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

Annotations already declare the operation is read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond annotations by noting that dimension ids are stable and that connected_source is present only when bound to a database. It does not discuss cache behavior, but the annotation coverage lowers the burden.

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

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

The description is two concise sentences with the main action front-loaded. The second sentence adds relevant details about return fields without unnecessary fluff.

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

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

For a simple read-only getter, the description covers the core purpose and some return-field semantics. However, there is no output schema, and the description omits details about the language and cache parameters, which matter for expected results. It is adequate but 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 coverage is only 50%, with project_id and version_id described but language and use_cache left undocumented. The description does not compensate for these gaps or clarify how language or caching affects results. It adds no parameter-level meaning beyond what the schema already provides.

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

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

The description clearly states the tool gets all dimensions of a project version, with a specific verb and resource. It also adds useful detail about the returned id and connected_source fields, but it does not explicitly distinguish this tool from closely related siblings like df_get_dimension_group or df_list_dimension_groups.

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 use this tool versus alternatives, nor does it mention exclusions or prerequisites. The only implied usage is that it fetches dimensions, but it does not clarify when to choose df_get_dimensions over related 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, idempotentHint, and destructiveHint, which cover the safety profile. The description adds no behavioral context beyond that—no mention of caching behavior, language handling, or return format. It contributes nothing beyond the structured 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 with no filler or redundancy. It is appropriately front-loaded and efficient, though it is arguably too terse to be maximally useful. Still, it earns credit for brevity and clarity.

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

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

Given a 4-parameter tool, a 50% schema coverage gap, and no output schema, the description is far from complete. It does not explain what 'facts' entails, how the optional parameters behave, or what the response looks like. An agent would need to inspect the schema or guess to call it correctly.

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

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

Schema coverage is 50%: project_id and version_id have descriptions, but language and use_cache do not. The description mentions no parameters at all, so it fails to compensate for the uncovered ones. The agent is left guessing about the meaning and impact of language and use_cache.

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 ('Get') and resource ('all facts of a project version'), making the core purpose unambiguous. However, it does not differentiate from sibling get-style tools (e.g., df_get_fact_table, df_get_dimensions), so an agent must rely on naming alone to distinguish 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 on when to use this tool versus alternatives, no mention of prerequisites or context, and no exclusions. The description is a bare statement of function with no direction for the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond that: it states what the fact table object contains and explains that include_dependencies=true returns the formula dependency tree for each measure. No annotation 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?

Two focused sentences with no filler. The core action and returned components are front-loaded, and the optional dependency behavior is added in a clear second 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?

Given the read-only annotations, required IDs documented in the schema, and the description's enumeration of returned content plus the dependency-tree option, the tool is adequately described for a single-object GET. The main omissions are explicit guidance on language/use_cache behavior and output formatting, but these are minor because no output schema exists and defaults are 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 description coverage is only 33%, so the description must compensate, and it does for include_dependencies by explaining its effect. However, it leaves language and use_cache semantically unexplained, and fact_table_id has no description either. It adds some value beyond the schema but does not fully cover the gaps.

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 one fact table') and enumerates the contents returned: measures, dimensions, facts, dimension groups, and verification filters. This clearly distinguishes it from sibling tools like df_list_fact_tables, which list fact tables rather than retrieving one.

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

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

The intended use is implied by 'Get one fact table' and the include_dependencies option, but there is no explicit when-to-use or when-not-to-use guidance and no named alternative. An agent can infer this is for detailed retrieval of a single fact table, but the description does not spell out the choice versus df_list_fact_tables or other read 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 idempotentHint=true, so the safety profile is covered. The description adds no behavioral context beyond the purpose, such as error behavior, return format, or cache semantics. It doesn't contradict the annotations but also contributes nothing beyond 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, front-loaded sentence with zero redundancy. It states the core purpose immediately and wastes no words, which is ideal for a simple get-by-id 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?

Given the tool's complexity (only 2 parameters, no output schema), a rich description is not required, but the description leaves critical gaps: use_cache is unexplained, and there is no guidance on how this relates to the git connection lifecycle tools. The agent cannot fully understand invocation semantics without additional inference.

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

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

Schema description coverage is 0%, and the description does not explain connection_id or use_cache. The agent can guess connection_id identifies the target, but use_cache's purpose is completely unspecified. The description fails to compensate for the empty schema descriptions.

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

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

The description states a specific verb ('Get') and resource ('one saved Git connection'), clearly distinguishing it from df_list_git_connections (plural listing) and df_get_connection (non-Git connection). An agent can immediately identify the tool's job 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?

There is no explicit guidance on when to use this tool versus df_list_git_connections or df_get_connection. The phrase 'one saved Git connection' strongly implies single-item retrieval by ID, but the description does not state exclusions 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral traits beyond those: automatic pagination and the ability to include generated SQL per measure via include_sql. This is useful context that is not in the annotations, so it earns a solid 4.

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

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

The description is two concise sentences with no filler. The primary purpose and pagination are front-loaded, and the optional include_sql behavior is stated clearly in the second sentence. 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 read-only tool with auto-pagination, the description covers the essential behavior and the significance of the returned IDs for write tools. It lacks detail on the response structure, but given the absence of an output schema and the simplicity of the operation, this is acceptable. The remaining gaps are minor, so a 4 is warranted.

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

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

The input schema describes project_id and version_id only, leaving language, use_cache, and include_sql without descriptions (40% coverage). The description compensates partially by explaining include_sql's effect, but it does not explain language or use_cache. Given the low schema coverage, the description should add more parameter detail; it does not fully compensate, so a 3 is appropriate.

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

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

The description states a specific verb ('Get all measures') and a specific resource ('of a project version'), and mentions automatic pagination. It is clear what the tool does, but it does not explicitly differentiate from sibling tools like df_get_facts or df_get_dimensions, though the resource name is distinct enough. This is clear but not explicitly contrasted with alternatives.

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

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

The description provides some usage context: it states that each measure carries a stable ID that write tools accept, implying this tool is used to obtain IDs for subsequent write operations. However, it does not explicitly state when to use this tool versus other read tools (e.g., df_get_facts) or when not to use it. The guidance is implicit rather than explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds a small amount of context by specifying exactly what is returned (owner and explicit users), but it does not disclose additional behavioral traits such as caching behavior or output format.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes to the meaning, and the core operation is immediately clear.

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 annotations, the core purpose is covered, and the return scope is stated. However, the description omits any explanation of the language and use_cache parameters, and there is no output schema to clarify the response shape.

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

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

Schema description coverage is 0%, so the description must compensate. It only references 'project' generally and fails to explain the project_id parameter, nor does it clarify the meaning of language or use_cache. This is a significant gap for the required 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 ('List') and a clear resource ('owner and every user with explicit access to a project'). It distinguishes itself from related siblings like df_set_project_access, df_revoke_project_access, and df_transfer_project_ownership by making clear this is the read-only retrieval operation.

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

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

The description implies the tool is used when you need to see project access, but it does not explicitly state when to use it versus alternatives or when not to use it. No exclusions or conditions are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds that the result includes foreign and primary key source objects, but says nothing about return format, errors, caching behavior, or language sensitivity.

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 entire description is one short, front-loaded sentence with no filler. It states the action and the key output scope efficiently.

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

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

With no output schema and low parameter coverage, the description gives only a surface-level idea of what is returnedteachers. It is adequate for a safe read operation but insufficient for an agent to understand optional parameters or the exact shape of the response.

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

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

Schema description coverage is only 40%, and the description does not compensate for the undocumented parameters. It only implicitly references relationship_id via 'one relationship' and provides no meaning for language or use_cache, and relationship_id itself lacks a schema 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 singular resource ('one relationship'), and enriches it by stating the returned data includes foreign and primary key source objects. This clearly differentiates it from sibling tools like df_list_relationships and df_delete_relationship.

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 singular 'one relationship' implies use with a specific relationship_id, but the description never explicitly states when to choose this over df_list_relationships or other relationship-related tools. There is no mention of exclusions, prerequisites, 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 establish readOnly, idempotent, and non-destructive behavior, so the bar is lower. The description adds meaningful behavioral context beyond annotations: it returns normalized semantic context, includes counts, and shares one API call and one cache entry with df_get_consolidated_rmd, which informs caching and performance expectations.

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 action and return contents are front-loaded, and the cache-sharing note is a single relevant addition. Every sentence earns its place.

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

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

For a read-only getter with simple parameters, the description covers the output shape at a high level and the safety profile is handled by annotations. However, it does not clarify when to choose this over df_get_consolidated_rmd despite the shared API call, and the undocumented parameters remain unexplained, which is a noticeable gap given there is no output 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 only 50%, and the description does not compensate for the undocumented parameters (language, use_cache, include_sql). It lists 'project, version' as part of the semantic context but adds no practical meaning to any parameter beyond what the schema already provides.

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

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

The description clearly states a specific verb ('Get'), a specific resource ('normalized semantic context of a project version'), and enumerates the returned contents (project, version, measures, dimensions, facts, counts). It references the closely related sibling df_get_consolidated_rmd, which helps distinguish it indirectly, though it does not explicitly define the difference between 'normalized' and 'consolidated'.

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

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

The description notes that it shares an API call and cache entry with df_get_consolidated_rmd, but gives no explicit guidance on when to use this tool versus the sibling or other get_* tools. There is no when-to-use or when-not-to-use information, leaving the agent to infer the routing decision.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context by naming the three aspects checked, but it does not describe output format, potential latency, or what the health result contains.

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, front-loaded sentence states exactly what the tool does with no filler, repetition, or unnecessary detail. Every word adds 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?

For a parameterless, read-only, idempotent health-check tool, the description fully covers what the agent needs to decide whether and when to call it. The annotations cover safety, and the description covers scope; no additional context is required.

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

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

The tool has zero parameters and the schema is trivially 100% covered, so the description does not need to document any parameters. The baseline of 4 applies because there is nothing missing for an agent to invoke the tool correctly.

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 ('Check') and clearly identifies three distinct resources: server health, DataForge API connectivity, and cache status. This distinguishes it from all sibling tools, none of which perform a general health check.

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 purpose implicitly tells an agent when to use it—when health, API connectivity, or cache status needs verification—but it does not explicitly state alternatives, exclusions, or conditions. Since there are no sibling health-check tools, this is adequate but not explicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description's main contribution is the explicit overwrite behavior for target_method=replace and the on-premises constraint. The blanket 'PERMANENTLY DELETES DATA' sentence adds dramatic context but is vague about what exactly gets deleted. Still, it adds useful behavioral nuance beyond the annotations.

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

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

Three short sentences with no filler; each adds a distinct piece of information. The warning is front-loaded, which is attention-grabbing but arguably overstates the tool's primary behavior. Overall it is appropriately sized, though the opening sentence could be more precise.

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 9 parameters, nested objects, and no output schema, the description is too thin. It covers only target_method and on-premises availability, omitting how file_path is used, what target_version_name must be, how conflict_strategy interacts with imports, and what the boolean options control. For a destructive import operation, this is a significant completeness 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 only 33%, so the description must compensate, but it only clarifies target_method=replace. It does not explain file_path, target_version_name, conflict_strategy, encryption_password, or any of the nested options. This leaves most of the 9-parameter surface underdocumented.

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 the specific operation: importing a version from a local .dfexport.zip archive, and distinguishes it from git-based import by noting 'local' and 'On-premises installations only.' However, the leading warning 'PERMANENTLY DELETES DATA IN DATAFORGE' is alarming and somewhat obscures the primary import purpose, though it does signal destructive potential.

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

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

It provides context: on-premises only, local archive, and explains that target_method=replace overwrites. However, it does not explicitly name alternatives such as df_import_version_from_git or df_preview_import, nor state when to prefer them. The 'local .dfexport.zip archive' implies the file-based path, but the guidance is not fully explicit.

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

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

Annotations already declare destructiveHint=true IDs, but the description adds substantial behavioral detail beyond that flag: permanent deletion, full overwrite of the version in the path, and the fact that conflict_strategy=overwrite also applies deletions. It also conveys that replace is destructive while create is not, which is crucial for an agent deciding how to set target.method. This goes above and beyond the annotation signals.

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

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

The description is compact and front-loaded with the most critical warning about permanent data loss, then proceeds to the main purpose and method semantics. Every sentence carries weight: the warning, the create vs. replace distinction, the prerequisite preview step, and the deletion implication of conflict_strategy. No filler or 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?

This is a complex tool with 12 parameters, nested objects, and no output schema. The description covers the critical behavioral aspects (destructive nature, method semantics, preview prerequisite) but omits guidance on other important parameters like authentication, options, commit_hash, and connection_id. Given the schema's own low description coveragetemp, some gaps remain. It is adequate for the high-risk aspects but not fully complete for a complex import operation.

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

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

Schema description coverage is low at 33%, and many parameters (e.g., path, commit_hash, connection_id, all of the options) are undocumented in both schema and description. The description does add real meaning to target.method (create vs. replace) and conflict_strategy=overwrite, which is helpful, but it leaves the agent to infer the purpose of most parameters from names alone. It partially compensates for the schema gap but does not fully cover it.

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

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

The description opens with a stark warning, then clearly states the tool's function: 'Import a version from Git.' It goes further by distinguishing the two target.method behaviors (create vs. replace, where replace overwrites the version entirely) and explicitly notes that conflict_strategy=overwrite also applies deletions. This makes the tool's purpose and destructive consequences unmistakable, and differentiates it from related import/export tools among the siblings.

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

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

The description provides the key prerequisite 'Run df_preview_import first,' which tells the agent when to call this tool relative to a sibling. It also implicitly warns against use in non-destructive contexts by highlighting permanent deletion and overwrite behavior. However, it does not name alternatives (e.g., df_import_version_from_file) or state when to choose this tool over them, so it falls short of full 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?

The annotations already mark the tool as read-only and idempotent, so the safety profile is covered. The description adds valuable behavioral context by stating that credentials are never returned and unsupported engines are excluded entirely.

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 primary purpose is front-loaded, and the security-relevant caveat about credentials is appropriately placed.

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 core listing behavior and key exclusions are clear, but the tool has eight parameters and no output schema. Optional filtering, pagination, language, and caching behavior are left entirely to schema defaults and enums, which is adequate but minimal.

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

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

Schema description coverage is only 25%, so the description must compensate for six undocumented parameters, but it does not. It never clarifies page, status, db_type, language, page_size, or use_cache; the single note about unsupported engines is a behavioral detail, not parameter guidance.

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: 'List database connections of a project version.' It is unambiguous and naturally distinguishes this tool from sibling tools like df_list_git_connections by limiting scope to database connections.

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

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

The description states the core action but provides no guidance on when to choose it over alternatives such as df_get_connection or df_get_connection_schema. No exclusions, conditions, or mention of related tools are given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds no new behavioral context. It does not mention pagination behavior, caching effects, or the meaning of filters such as use_cache, mart_type, or merge_type.

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

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

The description is a single, front-loaded sentence with no wasted words. It captures the core operation efficiently, though at the cost of omitting useful details.

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 9 parameters, no output schema, and many sibling tools, the description is too sparse. It does not explain pagination, filtering behavior, or what a 'data mart' listing includes, leaving significant gaps for an agent trying to invoke it correctly.

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

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

Schema description coverage is only 33%, and the description does not compensate for the undocumented parameters. It adds no meaning beyond the schema for optional filters like page, page_size, language, mart_type, merge_type, or use_cache, leaving agents to guess their roles.

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 ('List'), a clear resource ('data marts'), and a scoping context ('of a project version'). This distinguishes it from sibling tools like df_get_data_mart (retrieves a single mart) and df_list_fact_tables (a different resource type).

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

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

No guidance is provided about when to use this tool versus alternatives such as df_get_data_mart or df_list_fact_tables. There are no explicit exclusions, prerequisites, or conditions for choosing this listing 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds a clarifying parenthetical ('shared reference hierarchies') but discloses no further behavioral traits such as pagination, caching, or return format. With annotations present, the bar is lower, and the description adds minimal value beyond 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, efficient sentence with no wasted words. The core action and scope are front-loaded. It is appropriately terse for a 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 list tool with annotations covering safety, the description is adequate but minimal. It does not mention pagination, language, or cache parameters, though these have defaults and might be inferred. The lack of an output schema means return structure is not specified, but for a list operation this is acceptable. Given the many siblings, a bit more differentiation would help, but it is not critically incomplete.

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

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

Schema description coverage is only 33% – only project_id and version_id have descriptions. The description does not compensate for the missing parameter documentation (page, language, page_size, use_cache). It provides no additional meaning about these parameters, and since coverage is low, the description should fill the gap but does not.

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

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

The description clearly states a specific verb ('List') and a specific resource ('dimension groups') with a scope ('of a version'). It distinguishes itself from siblings like df_get_dimension_group (which likely retrieves a single group) and df_list_fact_tables (a different entity). The purpose is unambiguous.

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

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

The description implies usage context (listing dimension groups for a version) but does not explicitly state when to prefer this tool over alternatives like df_get_dimension_group or other list tools. There are no exclusions or alternative routing, so the guidance is only implied, not explicit.

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

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

Annotations already declare the operation as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful context that the result includes element counts, but it does not disclose behavior around pagination, caching, language, or response format. This is acceptable but not rich.

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 and front-loads the core purpose. It is appropriately concise for a simple list operation, though the brevity contributes to missing parameter-level guidance.

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

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

Given the pagination, language, and cache parameters, and the absence of an output schema, the description should provide more context about return structure, pagination behavior, and parameter effects. It only states that fact tables are listed with counts, which is incomplete for an agent trying to call the tool correctly with all optional parameters.

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

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

Schema description coverage is only 33%; only project_id and version_id have descriptions in the schema. The description adds no meaning for page, page_size, language, or use_cache, and it only restates the project/version scoping already implied by the required parameters. With low schema coverage, the description should compensate but does not.

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

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

The description clearly states a specific action ('List'), a specific resource ('fact tables'), a scope ('of a project version'), and an output detail ('with element counts'). This distinguishes it from siblings like df_get_fact_table and df_write_fact_table without needing to open schemas.

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

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

The description gives a clear scope ('of a project version') that implies when to use it, but it never explicitly says when to choose this over a sibling like df_get_fact_table or df_list_data_marts. There is no exclusion or alternative guidance, leaving some usage inference to the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: credentials are never returned, and a company administrator API key is required. This goes beyond the annotations.

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

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

Two sentences with no waste. The core purpose is front-loaded, and the security/credential note is a single additional sentence. 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 simple list tool with no output schema and only three optional parameters, the description covers the essential context: what it lists, the credential safety guarantee, and the auth requirement. It doesn't mention pagination behavior or cache semantics, but those are minor for a read-only list operation with self-explanatory parameter names.

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

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

Schema description coverage is 0%, so the description carries the burden for parameter semantics. However, the description doesn't explain the page, page_size, or use_cache parameters. The parameter names are fairly self-explanatory, and defaults are in the schema, but the description adds no meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists the company's saved Git connections, with a specific verb and resource. It also distinguishes itself from related tools like df_get_git_connection (singular) and df_list_connections (general connections) by specifying 'Git connections'.

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 this tool: when you need to list Git connections. It doesn't explicitly name alternatives or exclusions, but the sibling list shows df_get_git_connection for a single connection and df_list_connections for non-Git connections, providing enough context for an agent to differentiate.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds a permission-scoping constraint ('visible to the configured API key') but does not disclose pagination or cache behavior, which are only partially inferable from parameter names.

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. Every word adds signal: the verb, the resource, and the access scope.

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 with optional pagination and cache parameters, the core purpose is adequately covered. However, the lack of an output schema and any mention of return shape, pagination behavior, or cache semantics leaves 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 0%, and the description says nothing about page, page_size, or use_cache. The agent must rely entirely on parameter names, defaults, and constraints in the input schema, so the description adds no parameter-level meaning.

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

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

The description uses a concrete verb ('List'), a specific resource ('DataForge projects'), and a scope qualifier ('visible to the configured API key'). This clearly distinguishes it from sibling list tools targeting other resources such as data marts, versions, or connections.

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 sentence implies usage when a project list is needed, but it provides no explicit when-to-use or when-not-to-use guidance and does not name alternative tools. It relies on the agent to infer the appropriate context from the resource name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral details such as pagination behavior, caching semantics, or return shape, but it does not contradict the annotations. It provides only minimal context beyond the annotations, so a mid-range score is appropriate.

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

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

The description is short, front-loaded with the core action, and contains no filler. The second sentence about relationship_type adds a small but possibly useful detail. It earns its place, though it could have been integrated more clearly with the schema context.

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 8 parameters, no output schema, and no explanation of pagination, caching defaults, optional filters, or what the returned relationship objects look like. The description is sufficient to understand the intent but incomplete for an agent to confidently call the tool with the right parameters and interpret results.

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

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

Schema description coverage is only 25%, covering just project_id and version_id. The description mentions the fact-table-to-dimension-group join concept, which loosely maps to fact_table_id and dimension_group_id, but it does not explain page, page_size, language, use_cache, or the filtering semantics. With low schema coverage, the description should compensate, and it does not.

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

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

The description states a specific verb and resource ('List star-schema relationships') and clarifies the domain ('fact table to dimension group joins'), which distinguishes it from singular operations like df_get_relationship. It does not explicitly name sibling alternatives, but the purpose is clear and not tautological.

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 alternatives such as df_get_relationship, df_write_relationship, or df_list_dimension_groups. The context is limited to what the tool does; there are no exclusions, prerequisites, or conditions that would help an agent choose between listing and singular relationship 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds no extra behavioral context, such as pagination behavior, cache semantics, or output limits, but it is consistent with 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. It is efficiently structured for its brevity, even though that brevity limits the amount of useful guidance it can convey.

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

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

With no output schema and 0% parameter descriptions, this one-sentence description is not complete enough for an agent to fully understand the tool. Pagination, cache behavior, return format, and ordering/filtering rules are all left to inference; annotations cover safety but not these operational details.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It only implies that project_id identifies the target project, and says nothing about page, page_size, or use_cache. Some meaning can be guessed from the parameter names and defaults, but the description does not add value beyond them.

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' and identifies the resource as 'versions of a DataForge project,' making the core purpose clear. It is easily distinguished from sibling tools like df_create_version, df_update_version, and df_delete_version, though it does not explain what a version contains or what output to expect.

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 usage context is implied by the verb 'List': an agent can infer this is the tool for reading a project's version history. However, the description gives no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as export/import version tools or lower-level get 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?

The description explicitly states 'Nothing is written,' which is the key behavioral guarantee for a dry-run tool)Skip and adds value beyond the annotations by clarifying the operation has no mutation side effects. It also previews the output nature ('report what would change'), though it does not detail auth requirements, failure modes, or response structure.

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 tightly worded sentence front-loads the core intent ('Dry run'), states what it does, and includes the critical safety guarantee ('Nothing is written'). No filler or 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?

This is a high-complexity tool with 13 parameters, nested authentication, multiple enums, and no output schema. The description gives a clear high-level purpose but leaves the agent without sufficient guidance on how to construct the import source specification, what conflict_strategy means in a dry-run context, or what the returned report looks like. The sparse schema descriptions do not fill this 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 only 23%, and the description does not compensate by explaining the many parameters involved in specifying an import source (source_type, repository_url, authentication, file_path, branch, commit_hash, conflict_strategy, options). It only loosely references 'import source' and 'target version,' so an agent receives little help on how to populate the complex nested input.

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 operation ('Dry run: compare an import source with the target version') and a specific output ('report what would change, including per-field conflicts'). This clearly distinguishes it from the actual import siblings like df_import_version_from_git and df_import_version_from_file.

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

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

The 'Dry run' label and 'Nothing is written' clearly signal this tool is for previewing an import before applying it, which provides clear context for when to use it. However, it does not explicitly name alternatives or state when not to use it, so it stops short of full routing guidance.

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

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

Annotations already signal readOnly=false, destructive=false, idempotent=true. The description adds concrete context by naming what gets destroyed (the cached state) and what gets re-fetched (RMD snapshot), which goes beyond the structured fields 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?

A single, front-loaded sentence with no filler. Every phrase adds information: the resource, the scoping option, and the refresh action.

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

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

The description plus annotations are sufficient for a basic cache-refresh call, but the 'global' scope value, the role of the language parameter, expected side effects on subsequent reads, and return value are left unexplained. Without an output schema, that gap weakens completeness.

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

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

Schema coverage is only 50%: scope and language lack descriptions. The description adds minimal parameter meaning via 'or the whole project' hinting at scope but does not explain 'global' scope, the language parameter, or how project_id/version_id relate to the refresh. It does not compensate for the undocumented optional parameters.

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 ('Drop') and names the precise resource ('cached state of a project version or the whole project') plus the re-fetch action. This clearly separates it from sibling read tools like df_get_rmd and destructive tools like df_delete_version.

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 the use case—refreshing a stale cache—but never states when to choose this over alternatives or when not to use it. No explicit exclusions are provided, so an agent must infer the appropriate context.

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

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

Annotations declare destructiveHint=true, and the description reinforces this with a prominent warning: 'PERMANENTLY DELETES DATA IN DATAFORGE.' It adds behavioral context by explaining that only the group membership is removed, not the dimension itself, which is valuable beyond the annotations. It does not contradict annotations and provides additional clarity on scope.

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 concise, consisting of two sentences with zero filler. The critical warning about permanent deletion is front-loaded, and the clarifying note about the dimension remaining in the RMD follows immediately. 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?

Given the tool's simplicity (a single removal operation with no output schema) and the annotations covering idempotency and destructiveness, the description covers the essential points: what it does, what is deleted permanently, and what is preserved. It does not discuss edge cases like removing a non-existent dimension or behavior on repeated calls, but the idempotentHint annotation covers repeat behavior. Overall, it is sufficiently complete for an agent to call it correctly.

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

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

Schema description coverage is only 50% (project_id and version_id have descriptions; dimension_group_id and dimension_id do not). The description says 'Remove one dimension from a group,' which implicitly maps dimension_id to the dimension and dimension_group_id to the group, but it does not explicitly explain these parameters. The names are somewhat self-explanatory, but the description adds minimal value beyond what the schema already conveys, and it does not fully compensate for the missing schema descriptions.

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

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

The description clearly states the action: 'Remove one dimension from a group' with a specific resource (dimension group). It also clarifies that the dimension itself remains in the RMD, distinguishing it from deleting the dimension entirely. This differentiates it from siblings like df_delete_dimension_group or df_set_group_dimensions, making the purpose unambiguous.

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

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

The description implies when to use this tool (to remove a single dimension from a group) and notes the dimension is not deleted, but it does not explicitly mention alternatives like df_set_group_dimensions or df_delete_dimension, nor does it state conditions for when to prefer this over them. The guidance is implicit rather than explicit, which is adequate but not thorough.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the description's warning 'PERMANENTLY DELETES DATA IN DATAFORGE' adds emphasis beyond the annotation, clarifying the irreversible nature. It also specifies 'explicit access,' which clarifies the scope of what is removed. This adds useful context beyond the annotations without 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?

The description is two sentences, concise and front-loaded with the warning. However, the warning 'PERMANENTLY DELETES DATA IN DATAFORGE' is somewhat alarming and could be misinterpreted (e.g., as deleting the user or project itself), which may mislead an agent. It earns its place by highlighting destructiveness, but the phrasing is ambiguous.

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 revoke operation, the description is adequate. It states the action and implies the required parameters. The annotations cover idempotency and destructiveness, so the description does not need to repeat those. It does not mention edge cases (e.g., behavior when no explicit access exists), but given the idempotent annotation, this is less critical. Overall, sufficient for correct invocation.

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

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

The schema has 0% description coverage, so the description must compensate. It references 'a user's explicit access to a project,' implying the user_id and project_id parameters and their purpose. However, it does not elaborate on parameter types, formats, or relationships beyond what the names suggest. Given the low coverage, this is adequate but not rich.

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: 'Remove a user's explicit access to a project.' It identifies the verb (remove), the resource (user's explicit access to a project), and it is distinguishable from siblings like df_set_project_access (which grants access) and df_get_project_access (which retrieves access). The purpose is unambiguous.

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

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

The description implies usage: when you need to revoke a user's explicit access. However, it does not explicitly mention alternatives or when not to use it (e.g., when you want to grant access, use df_set_project_access). It provides the core context but lacks explicit routing to siblings.

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