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

With no annotations, the description carries the full burden of behavioral disclosure, but it only states the operation. It does not mention whether the operation is destructive, what happens if fields already exist, whether it requires specific permissions, or what the response format is. It adds no behavioral context beyond the trivial.

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 sentence that is front-loaded with the purpose, which is good. However, it is so terse that it omits necessary context. It is concise but under-specified, bordering on under-specification rather than effective conciseness.

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 has three required parameters and an output schema, the description is incomplete. It does not mention prerequisites, error conditions, or the shape of the response. Even though an output schema exists, the description should at least indicate that a confirmation is returned or any side effects. It is minimal to the point of being insufficient.

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 does not explain any of the three parameters. The schema provides a description for 'fields' with an example, but 'workspace_id' and 'category_id' are undocumented. The description fails to compensate for the 33% schema coverage, leaving the agent without guidance on what these IDs refer 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 clearly states the action ('Add fields') and the resource ('an existing category'), with the HTTP endpoint as technical context. This distinguishes it from sibling tools like docflow_update_category_field (which updates existing fields) and docflow_create_category (which creates a category). The verb and resource are specific and 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 no guidance on when to use this tool versus alternatives. It does not mention related tools like docflow_update_category_field or docflow_list_category_fields, nor any conditions that would select this tool. An agent would have to infer usage from the name alone.

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

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

No annotations are provided, so the description carries full behavioral burden. It discloses the API action (POST), implies a mutation (upload), and states a hard limit (max 10). However, it does not mention side effects like whether samples are appended or replaced, whether the operation is reversible, or any preconditions. This is adequate 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?

Two sentences, zero fluff. The main action and purpose are front-loaded, and the second sentence gives actionable guidance. The endpoint in parentheses is a useful reference, not filler. 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?

Covers the core purpose and a key limit, and an output schema exists so return values need no explanation. Missing context includes the meaning of sample_file_paths, any interaction with existing samples, and conditions for successful upload. Given the low schema coverage, the description should have filled more 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%, so the description must compensate, but it only refers generically to 'sample files' without explaining sample_file_paths semantics (paths? URLs? local vs remote?). The parameter names are self-descriptive, yet the description adds no detail about the array format, file requirements, or constraints beyond max 10. This is below the minimum viable baseline.

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

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

States a specific verb and resource ('Add sample files to a category') plus the purpose ('improve classification accuracy'). The endpoint reference further disambiguates from sibling operations like docflow_add_category_table or docflow_add_category_fields. An agent can easily tell 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?

Provides concrete context on when and how many to add ('3–5 recommended, max 10 total'), which is useful for effective use. It does not explicitly mention alternatives or when-not-to-use, but the sibling names make the distinction obvious. The quantity guidance earns this above a 3.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states that the tool adds a table field group, but it does not mention whether the operation is destructive, whether it requires special permissions, whether it is idempotent, or what effect it has on existing category data.

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 crisp sentences: the first states the operation and endpoint, the second gives a concrete usage context. There is no filler or repeated 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?

The description plus schema provides enough to attempt the call: it names the resource, gives an example, and the schema documents required parameters and the fields format. However, behavioral details such as mutation effects and permission expectations are missing, and two parameters are undocumented in both the schema and description.

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

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

Schema description coverage is only 50%, and the description does not compensate for the missing parameter details. It adds no meaning to workspace_id or category_id beyond their names, and it does not explain how the examples like 'invoice line items' map to the fields array structure beyond what the schema already says.

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

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

The description uses a specific verb plus resource: 'Add a table field group to a category.' It also includes the endpoint, which makes the operation unambiguous and differentiates it from sibling tools like docflow_add_category_fields or docflow_update_category_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?

It gives a clear use case: 'Use for extracting structured table data (e.g. invoice line items, hotel charges).' This tells the agent when the tool is appropriate, though it does not explicitly state when not to use it or name a specific alternative.

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

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

With no annotations provided, the description carries the full burden of behavior disclosure. It clearly reveals that calling this tool triggers re-extraction and reprocessing with the correct category's field configuration, which is a meaningful side effect beyond the simple action of updating a category.

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

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

The description is compact and well-structured: the main action and side effect are front-loaded, followed by a clear usage condition. Every sentence provides useful information with no filler.

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

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

The core purpose and side effect are covered, and the presence of an output schema reduces the need to describe return values. However, the 0% parameter schema coverage and lack of annotations leave gaps around required parameter semantics and preconditions, making the description only minimally 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 0%, so the description must compensate for explaining the parameters. It only implies the meaning of 'category' via the phrase 'correct category's field configuration,' but does not explain workspace_id or task_id, leaving the agent 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 states a specific action—correcting a misclassified file's category—and names the key side effect of triggering re-extraction. It also includes the exact endpoint, making the tool's intent unambiguous and distinguishing it from generic file update or retry tools.

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

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

The description explicitly states when to use the tool: 'Use when a file was classified into the wrong category.' It does not name alternative tools or when-not-to-use conditions, but the stated use case is clear and actionable.

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

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

No annotations are provided, so the description carries the full burden, but it only states the action without any side effects or behavioral context. It does not mention persistence, conflict behavior on duplicate category names, what happens to the sample file, or that extract_model defaults to 'llm'.

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 communicates the essential create action and the two notable creation components 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?

The schema is rich enough to make the tool invocable, and the output schema exists so return values need not be explained. However, the description lacks broader workflow context, side-effect expectations, and prerequsite awareness, leaving an agent to infer the surrounding setup process.

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

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

The input schema already covers 100% of parameters with descriptions and default values, so the baseline is 3. The description adds only high-level mention of field configuration and a sample file, while the schema provides the concrete array format and extract_model 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 ('Create') and resource ('file category') and highlights the two key creation payloads ('field configuration' and 'sample file'). It is clear enough to distinguish from sibling list/update/delete category tools, though it does not explicitly contrast with docflow_amend_category or docflow_update_category.

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 this should be used instead of related tools like docflow_amend_category or docflow_update_category. It also omits prerequisites such as the workspace needing to exist or that this is likely an initial-setup step before extraction/review 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?

With no annotations, the description carries the transparency burden and largely succeeds: it warns that existing files retain extracted data while future uploads will no longer match the category. It does not address reversibility or permission requirements, but the most important side effect is disclosed.

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

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

Two concise sentences: the first states the core operation, the second gives a high-value warning. There is no filler, and the most important behavioral caveat is front-loaded.

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

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

Coverage is strong for a delete operation: it includes the affected resource and the data retention consequence, and an output schema exists to describe return values. Minor gaps remain around cascading effects and whether deletion is permanent, so it is not a perfect 5.

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 0% and the description does not explain workspace_id or category_id beyond the operation itself. The parameter names are self-explanatory, but the description adds no semantic value for how to populate or validate 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 states a specific action (delete), a specific resource (file category), and an additional scope (its field configuration), which clearly distinguishes it from sibling tools like delete_category_fields or delete_files. The endpoint reference reinforces the 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 usage: call this to delete a category. It also gives a practical caveat about future uploads, but it does not explicitly say when to prefer this over amend_category, delete_category_fields, or update_category, nor does it provide 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. 'Delete' clearly implies a destructive mutation, but the description does not state whether deletion is permanent, whether it affects existing category data, whether permissions are required, or what happens to related field definitions.

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 focused sentence with no filler. The action is front-loaded and the endpoint reference is compact and relevant. It earns its place without unnecessary detail.

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

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

For a destructive tool with no annotations and zero schema descriptions, this description is too thin. It lacks usage context, behavioral caveats, and prerequisite guidance. Output schema exists so return values need not be detailed, but the surrounding operational context is still missing.

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

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

Schema description coverage is 0%, so the description must compensate, but it only paraphrases 'fields from a category.' The parameter names field_ids, category_id, and workspace_id are somewhat self-explanatory, yet the description does not clarify their relationships, constraints, or how the IDs should be obtained.

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 exact action and resource: 'Delete fields from a category.' This unambiguously distinguishes it from sibling tools like delete_category, add_category_fields, or delete_category_samples, so an agent knows precisely which tool to pick.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no mention that field_ids should come from list_category_fields. The description merely restates the operation without giving an agent decision 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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. The word 'delete' signals destructiveness, but the description doesn't state whether deletion is permanent, whether it affects underlying files, whether it requires special permissions, or what happens to sample data used in classification. This is a meaningful gap for a destructive operation.

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

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

Two concise sentences with no filler. The core action and resource are front-loaded, and the use-case sentence earns its place by guiding when the tool should be invoked.

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

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

For a 3-parameter destructive tool with no annotations, the description is minimally adequate: it says what is deleted and why. However, it leaves out important context such as permanence, relationship to docflow_delete_files, and how sample_ids are obtained. The presence of an output schema helps but doesn't cover these operational 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 only hints that sample_ids refer to 'sample files from a category.' It doesn't explain how to obtain sample_ids, what format they use, or how category_id and workspace_id relate. The parameter names are self-explanatory to a degree, but the description does not compensate for the complete lack of schema parameter documentation.

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 ('Delete sample files'), a specific resource ('from a category'), and even names the underlying endpoint. This clearly distinguishes it from sibling tools like docflow_delete_files or docflow_delete_category.

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

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

The description gives an explicit use case: 'remove low-quality or irrelevant samples that hurt classification accuracy.' It doesn't mention when not to use it or point to alternatives, but the context is clear enough for an agent to choose it over related delete 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the destructive action ('Delete') but does not mention irreversibility, cascading effects on associated data, permission requirements, or what happens to dependent configurations. This is a significant gap for a destructive tool.

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

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

The description is a single, direct sentence with no filler, and the endpoint is useful context. It is concise and front-loaded, though it sacrifices explanatory depth for brevity.

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

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

Despite being a simple destructive tool, the description is too thin given the absence of annotations and schema descriptions. An agent cannot determine what valid table_ids look like or whether deleting table configurations triggers side effects. The output schema helps with return values but not invocation semantics.

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 0% schema description coverage, the description must compensate by explaining parameters, but it only says 'from a category', which implies category_id. It does not explain table_ids (e.g., that they are configuration IDs from a list call) or why workspace_id is required, leaving agents to infer from property names alone.

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

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

The description clearly identifies the action (delete), the resource (table configurations), and the scope (from a category), and includes the HTTP endpoint. This distinguishes it from siblings like docflow_delete_category, which deletes the category itself, and docflow_delete_files, which deletes files.

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 docflow_update_category_table (to modify rather than delete) or docflow_list_category_tables (to retrieve IDs). No prerequisites, exclusions, or workflow context are provided; the use case is only implied by the name.

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

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

No annotations are provided, so the description carries the behavioral burden. It explicitly warns 'Deletion is permanent,' which is critical for a destructive operation, and constrains the scope to 'processed files.' It does not detail side effects on downstream review results, but the core irreversibility is disclosed.

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

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

The description is two sentences with no filler. It front-loads the action, then adds the endpoint, selector requirement, and the permanent-deletion warning — 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 simple three-parameter destructive tool with an output schema, the description covers what is deleted, how to select targets, and that deletion is permanent. Minor gaps remain around what happens if both selectors are supplied or if neither is provided, but the core call is adequately specified.

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 0% schema description coverage, the description must compensate. It names task_ids and batch_numbers and explains that either may be used, which is useful. However, it does not explain workspace_id or the exact semantics of the identifier values beyond what the parameter names already imply.

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 ('Delete'), a specific resource ('processed files from a workspace'), and the endpoint. This clearly distinguishes it from unrelated delete siblings such as docflow_delete_workspace or docflow_delete_category.

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

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

It gives clear invocation guidance ('Provide either task_ids or batch_numbers') and implies scope via 'processed files', but it does not explicitly say when to choose this tool over alternatives like retry_files, update_file, or fetch_files. The usage context is implied rather than stated.

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

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

With no annotations, the description carries the behavioral disclosure burden. It explicitly warns that deletion is permanent and clarifies that existing review task results are not affected. These are the most important behavioral facts for a destructive operation, though permissions and failure modes are not covered.

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 tight sentences with no filler. The action and scope are front-loaded first, and the critical permanence warning follows immediately.

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

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

For a destructive two-parameter tool with an output schema, the description covers the essential behavior: cascade deletion, permanence, and non-impact on existing task results. It lacks explicit parameter guidance, but the required fields and their names are present in the schema, so an agent has enough 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 0%, and the description does not explain workspace_id or repo_id. The parameter names are meaningful in context, but the description adds no direct parameter-level meaning, so the agent must infer which identifier refers to the repository and which scopes the operation.

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 review rule repository and all its groups and rules'. This clearly distinguishes the tool from sibling tools that delete individual review rule groups or rules, and the endpoint is also included.

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 clear from the action, but the description does not explicitly say when to choose this over delete_review_rule_group or delete_review_rule, nor does it provide when-not conditions. The cascade scope implies the usage, but alternative routing is left to inference.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It states the delete action but does not mention permanence, cascading effects, auth requirements, or failure behavior. This is a destructive operation, so more cautionary detail 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 one focused sentence with the endpoint clear in parentheses. It is concise and front-loaded, though slightly under-specified for a destructive 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?

The tool is simple, but it is destructive and has no annotations or parameter explanations. The description is too thin to give the agent enough confidence about invocation semantics, workspace scoping, or what happens after deletion. The presence of an output schema helps, but does not fill the usage and behavioral 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 adds no parameter details. The parameter names 'rule_id' and 'workspace_id' are somewhat self-explanatory, but the description does not clarify relationships or expected values beyond what the bare schema already implies.

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

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

The description clearly states the action and resource: 'Delete a review rule', and reinforces it with the endpoint. This distinguishes it from sibling tools like update_review_rule and setup_review_rules, though it does not explicitly call out alternatives.

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

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

No guidance is provided for when to use this tool versus related tools such as docflow_delete_review_rule_group or docflow_update_review_rule. The agent must infer usage solely 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?

No annotations are provided, so the description carries the behavioral disclosure burden. It clearly states the destructive scope: the group and all rules within it are deleted, which is important side-effect context beyond the tool name. It does not discuss reversibility or permissions, but the explicit cascade behavior is a significant 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 a single sentence with no filler. It front-loads the action and cascade scope, and the parenthetical endpoint adds useful routing information without bloating the text.

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

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

For a low-complexity two-parameter delete operation, the description names the resource, the endpoint, and the key cascade side effect; the presence of an output schema covers return-value expectations. It lacks explicit parameter semantics and preconditions, but those are minor for this tool.

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

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

Schema description coverage is 0% and the description does not explain 'group_id' or 'workspace_id' beyond relying on their self-evident names. It adds no meaning about the required identifiers, relationship between workspace and group, or expected formats.

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 exact 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 gives no explicit when-to-use guidance, prerequisites, or exclusions relative to siblings like 'docflow_delete_review_rule'. An agent must infer the intended use from the name and action alone.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It merely says 'Delete review tasks', which implies destructiveness but does not state whether deletion is permanent, reversible, or scoped to the given workspace_id. No information about side effects, permissions, or errors is given.

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 sentence with no redundant words. It front-loads the action and appends the endpoint, which is useful but not essential. It is well-structured and concise, though under-specified.

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, the description is minimal but lacks essential context such as the relationship between workspace_id and task_ids, what a review task is, and the expected outcome. The presence of an output schema covers return values, but behavioral and usage gaps remain significant for an AI agent to invoke this tool correctly without additional investigation.

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 what task_ids or workspace_id mean, how they relate, or what formats are expected. The agent must rely solely on the parameter names, which are ambiguous without additional context.

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 and resource: 'Delete review tasks'. It also adds the API endpoint '(POST /review/task/delete)', which adds specificity. However, it mostly restates the tool name and does not distinguish itself from other review-task siblings beyond the obvious 'delete' action, so it falls short of a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives such as docflow_retry_review_task or docflow_get_review_result. There is no mention of prerequisites, context, or when not to use it, leaving the agent to infer usage solely from the name.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explicitly warns that deletion is permanent and lists the affected contents (files, categories, review rules), which is valuable for a destructive operation. It could add more about auth requirements or undo options, but the core risks are clearly communicated.

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 wasted words. The main action is front-loaded, and the critical warning is placed prominently. The structure is highly scannable and effective for an agent deciding whether to call this destructive tool.

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

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

For a one-parameter destructive operation with an output schema, the description covers the essential context: what is deleted, the endpoint, and the severe consequences. It does not discuss prerequisites or alternative deletion paths, but those are not critical for invoking this tool correctly. The warning about permanent deletion and affected entities makes it sufficiently 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?

There is only one parameter, workspace_id, and the schema provides no description for it (0% coverage). The tool description indirectly clarifies that the parameter identifies the workspace to delete, but it does not explicitly explain the parameter format or how to obtain a valid workspace_id. The meaning is inferable from the tool name and description, so this is adequate but not richly detailed.

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 ('Delete'), a clear resource ('a workspace'), and the scope of the operation ('all its contents'). It also names the endpoint, making the tool's action unambiguous and distinct from sibling tools like docflow_delete_category or docflow_delete_files.

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

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

The description clearly implies this tool is for deleting an entire workspace, not individual files or categories. However, it does not explicitly mention alternative tools or state when not to use it, so the usage 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?

With no annotations, the description must disclose behavior on its own. It communicates that the operation is a re-extraction on an already-processed file, which is useful and goes beyond the schema. However, it does not mention side effects, whether the extraction is synchronous/asynchronous, or any error/state implications, leaving part of the behavioral burden unmet.

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 tightly worded sentences. The first sentence states the action and endpoint; the second gives the usage condition. No filler words or duplication of schema 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?

Given the output schema exists and parameter descriptions are complete, the only missing context would be operational details like task prerequisites. The description ensures the agent knows the file must already be processed. It does not explicitly mention that workspace_id and task_id are required, but the schema marks them required, so this is adequately 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 100%, so the structured descriptions already explain each parameter. The tool description only adds general context about extracting 'specific fields' and does not add further meaning to the fields/tables formats beyond what the input schema provides. Baseline of 3 is appropriate.

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

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

The description uses a specific verb phrase 're-extract specific fields from an already-processed file' and includes the endpoint. It clearly distinguishes this from the upload-and-extract sibling by emphasizing 'without re-uploading the file', so an agent can tell them apart.

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

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

It explicitly states when to use the tool: 'when you need to extract additional fields without re-uploading the file, or when the original extraction missed certain fields.' It does not name the sibling alternative explicitly (e.g., docflow_upload_and_extract), but the context makes the alternative obvious. No exclusions or when-not-to-use guidance is given, hence a 4 rather than 5.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses the read-only nature via the GET method and gives a meaningful status legend (0=pending, 1=success, 2=failed, 3=processing) that helps an agent interpret returned results. It does not cover pagination or filtering behavior, but the core safety and result-interpretation traits are present.

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

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

Three sentences with no filler; the primary purpose and endpoint are front-loaded, and each sentence adds distinct value: the action, the usage scenario, and the status legend.

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 output schema covers return shape, and the description nails the core purpose plus the key status filter. However, six of seven parameters remain semantically opaque with zero schema descriptions, so constructing filtered queries (by file_id, category, batch_number) would be guesswork. Adequate for a minimal workspace_id-only call, but incomplete for full filtering use.

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 across all 7 parameters. It only explains recognition_status with its value mapping; file_id, category, batch_number, page, and page_size receive no semantic guidance beyond their names and types.

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

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

States a specific verb and resource — 'Query processed files in a workspace' — augmented by the explicit REST endpoint (GET /file/fetch). This clearly distinguishes it from sibling write/action tools like docflow_upload_and_extract, docflow_update_file, and docflow_delete_files.

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

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

Provides concrete usage context: 'Useful for checking status of previously uploaded files or retrieving results later.' This makes the intended scenario clear, though it does not name alternatives or exclusion conditions (e.g., when to prefer docflow_retry_files for failed items).

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

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

With no annotations, the description must carry behavioral disclosure. It does state the core behavior (find-or-create), the return values, and implies idempotency ('ensure a workspace is ready'), but it doesn't disclose side effects about existing workspaces or parameter interactions like enterprise_id.

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 brief, front-loaded with the action, and includes return values and usage guidance. Every sentence adds value without 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 such a simple get-or-create tool, the description covers action and return values. However, it leaves the optional parameters (description, enterprise_id) undocumented in both schema and description, and doesn't explain behavior when a workspace with the same name already exists under a different enterprise.

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 explain the parameters. It only hints at 'name' via 'by name'; description and enterprise_id are left completely unexplained. That is not enough compensation for the schema 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 opens with a clear verb-resource pair: 'Find a workspace by name, or create one if it does not exist.' It distinguishes itself from siblings like docflow_get_workspace by indicating lookup is by name and from docflow_create_workspace by indicating it won't duplicate.

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 tells the agent to use it 'as Step 1 of every workflow to ensure a workspace is ready,' which is a clear when-to-use signal. It does not name sibling alternatives or specify when not to use, so not a full 5.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It explicitly states this is a GET operation and frames it as inspection, which implies a non-mutating read. It does not mention auth or error behavior, but that is acceptable for a simple read tool.

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

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

Two efficiently written sentences: the first states the verb, resource, scope, and endpoint, while the second gives a practical usage guideline. Every sentence earns its place with no filler.

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

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

The description covers the tool's purpose and read-only nature, and an output schema exists to document the return shape. However, the two required parameters are entirely undocumented, and no alternative or exclusion is mentioned. It is minimally viable but not fully self-sufficient.

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

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

Schema description coverage is 0%, so the description must compensate for the undocumented parameters, but it does not. Neither workspace_id nor repo_id is explained; only the word 'repo' appears indirectly in the resource name. The agent is left to infer parameter meaning from naming conventions alone.

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

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

Clearly identifies a GET operation for a specific resource, 'review rule repository', and defines its scope as 'all its groups and rules'. This distinguishes it from the sibling list_review_repos, which likely returns only repository summaries. The inclusion of the endpoint further removes ambiguity.

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

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

Provides a concrete usage context: 'Use this to inspect existing rule configurations before making changes.' This tells the agent when to invoke the tool, but it does not explicitly name alternatives or state when not to use it.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the non-blocking nature ('without waiting') and enumerates meaningful status values, including pending, reviewing, and recognition_failed. It does not explicitly state that the call is read-only, but 'Get the current result' strongly implies it.

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: purpose and endpoint first, usage guidance second, and the status legend last. Every sentence contributes useful information with 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 simple two-parameter status polling tool, the description covers the core call context, non-blocking behavior, and result statuses. Since an output schema exists, return-value details are not required; the main gap is parameter-level guidance, but the overall description is 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 input schema has 0% description coverage, and the tool description does not explain task_id or workspace_id semantics, formats, or how they relate. The parameter names are somewhat self-explanatory, but the description does not compensate for the missing schema field 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 uses a specific verb 'Get' with a specific resource 'result of a review task' and clarifies it is non-blocking ('without waiting'). This clearly differentiates it from siblings like docflow_run_review and docflow_retry_review_task, which perform different actions.

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 explicitly states when to use the tool: to check status of a previously submitted review or for manual polling. It does not explicitly name alternatives or exclusions, but the 'previously submitted review' phrasing implies the appropriate place in the workflow after submitting a review.

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

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

No annotations are provided, so the description carries the full burden. It states the tool returns workspace metadata including name, description, auth_scope, and statistics, which is useful. However, it doesn't disclose whether this is a read-only operation, whether it requires special permissions, what happens if the workspace doesn't exist (error behavior), or any rate limits. The description is a simple GET, so read-only is implied but not stated.

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, front-loaded with the main purpose and endpoint, followed by return-value details. It is concise and every sentence adds information. No fluff or repetition.

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

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

The tool has an output schema, so return values are documented elsewhere. The description covers the main purpose and the key metadata fields. However, with no annotations and no parameter semantics, an agent might not know how to obtain workspace_id or what errors to expect. For a simple read tool, this is adequate 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 0%, and the description only mentions 'workspace_id' implicitly via the endpoint. It doesn't explain what workspace_id is, where to find it, or its format. The description adds no meaning beyond the schema's bare type declaration. With only one parameter, the description should have at least explained how to obtain the workspace_id.

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: getting detailed information about a specific workspace, and even includes the endpoint path. It distinguishes itself from siblings like docflow_list_workspaces (which lists workspaces) and docflow_get_or_create_workspace (which creates if missing), though it doesn't explicitly name them.

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

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

The description implies usage: call this when you need details about a specific workspace. It doesn't explicitly state when not to use it or mention alternatives like docflow_list_workspaces for listing all workspaces. The context is clear enough for an agent to infer, but no explicit routing guidance is provided.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It states the tool returns a list of category objects with specific fields, which is useful. However, it doesn't disclose whether the list is paginated, sorted, or limited in any way, nor does it mention error behavior or permissions. The return format is partially covered by the output schema, but the description adds the 'enabled' filter and the field configurations detail.

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 waste. The first sentence states the core function and scope, and the second sentence provides usage context. It is front-loaded with the most important information and 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 simple list tool with one parameter and an output schema, the description is nearly complete. It covers what the tool does, what it returns, and when to use it. The only gaps are minor: no mention of pagination or sorting, and no explicit statement about what happens if the workspace doesn't exist. Given the tool's simplicity, these are acceptable 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%, so the description must compensate. It mentions 'in a workspace' which maps to the workspace_id parameter, but doesn't explain the format, requiredness, or any constraints. The description adds minimal meaning beyond the schema—it tells the agent that workspace_id identifies the workspace to list categories from, but doesn't elaborate on how to obtain it or any edge cases.

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

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

The description states a specific verb ('List'), a specific resource ('all enabled categories in a workspace'), and includes the key output fields (name, category_id, fields). It clearly distinguishes this from sibling tools like docflow_create_category and docflow_list_category_fields by focusing on listing configured categories with their field configurations.

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

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

The description provides clear context: 'Use this to check which categories are already configured before creating new ones.' This tells the agent when to use it, though it doesn't explicitly name alternatives or exclusions. The sibling list includes docflow_create_category, so the usage guidance is helpful but could be more explicit about when not to use it.

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

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

No annotations are provided, so the description carries the full burden. It clearly signals a read-only operation with 'List' and 'GET', and it transparently describes the return contents: field_id, name, description, and configuration. It does not mention pagination or permissions, but for a list operation the behavioral profile is largely clear.

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 with no filler: action, return summary, and usage guidance. The most important information is front-loaded, and 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?

Given the tool's simplicity, two parameters, and the presence of an output schema, the description is largely complete. It provides the endpoint, return fields, and a practical use case. The main missing piece is workspace_id semantics, but that is already captured under parameter semantics.

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 little to explain the two required parameters. While category_id is implied by 'in a category', workspace_id is not described at all, and no format, source, or relationship guidance is given. The description should compensate for the bare schema 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 uses a specific verb and resource: 'List all fields configured in a category.' It also distinguishes this from siblings like docflow_list_categories and docflow_list_category_tables by naming the exact resource type and including the endpoint. An agent can immediately tell what this tool does and what it is not for.

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 concrete use case: 'Use this to get field_ids needed when building review rules with referenced_fields.' This gives clear context for when to invoke the tool, though it does not explicitly state when not to use it or name alternatives beyond the implied sibling set.

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

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

With no annotations, the description carries the burden of behavior disclosure. It communicates a read-only list operation ('GET /category/sample/list') and specifies the response contents (sample_id, file name, upload time), but it does not mention pagination, auth, or other operational edge 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?

Two succinct sentences: the first states the operation and endpoint, the second describes the returned fields. Every sentence is useful and there is no filler or redundant schema repetition.

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

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

The output schema covers return structure, so the description does not need to re-enumerate it. The description gives the endpoint, scope ('for a category'), and response gist, which is adequate for a simple list tool; only minor details like pagination or authorization are omitted.

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 for the undocumented parameters. It mentions 'category' only indirectly and never explains workspace_id or category_id semantics beyond what the parameter names already suggest. The description adds no meaningful parameter-level information.

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 all sample files configured for a category'. It also includes the HTTP endpoint and enumerates the returned fields, making the tool's function unambiguous and differentiating it from sibling tools like docflow_list_categories or docflow_list_category_tables.

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 when you need sample files for an existing category. However, it does not explicitly contrast with sibling list tools, nor does it state when not to use it or any prerequisites beyond the required parameters.

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

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

With no annotations, the description carries the full burden. It implies a read-only operation via 'List' and the GET endpoint, and mentions it 'Returns' data. However, it does not explicitly state that it has no side effects or require any permissions, and does not disclose any limitations like pagination. For a simple list operation, this is adequate 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 two sentences: the first states the operation and endpoint, the second states the return and use case. It is front-loaded, has no filler, and every sentence adds value. Highly concise.

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 an output schema, the description covers purpose, return fields, and a common use case. However, it omits any explanation of the parameters, which are essential for correct invocation. This gap makes it incomplete for an agent that needs to know what to pass for workspace_id and category_id.

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 the two required parameters (workspace_id, category_id). It mentions 'category' but does not clarify what the IDs refer to or their format. Since coverage is low, the description must compensate, and it fails to do so, leaving the agent guessing about 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 uses a specific verb 'List' and resource 'table configurations in a category', includes the endpoint (GET /category/tables/list), and states the return fields (table_id, name, fields). It clearly differentiates from sibling tools like docflow_list_category_fields (which lists fields) and docflow_add_category_table (which adds), so an agent can select it correctly.

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

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

The description explicitly states when to use it: 'Use this to get table_id before adding table fields or building review rules.' This provides a clear context and purpose. It does not mention when not to use or alternatives, but the guidance is specific enough for the primary use case.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It openly states this is a GET operation, implying read-only behavior, and specifies the returned fields (repo_id, name, creation time). It does not cover auth, errors, or pagination, but does establish the core side-effect profile.

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 tight sentences with no filler. It front-loads the main purpose, provides the exact endpoint, and summarizes the response shape 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?

The description is adequate for a simple listing tool and the output schema handles return values, but it leaves the sole parameter semantically underspecified and gives no guidance on when to prefer this over related review-repo tools. More parameter and usage context would make it fully complete.

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

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

Schema description coverage is 0% and the description does not explain the workspace_id parameter. It only refers to 'in a workspace' in a general way, which weakly implies the parameter's role. The description should explicitly state that workspace_id identifies the workspace whose repositories are listed.

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 ('List all review rule repositories'), the scope ('in a workspace'), and the exact endpoint. It is easily distinguished from sibling tools like docflow_get_review_repo or docflow_update_review_repo because the resource and listing behavior are explicit.

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

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

The description clearly implies when to use the tool: when the agent needs an overview of all review rule repositories for a given workspace. It does not explicitly mention alternatives or exclusions, but the 'list all' framing and workspace context provide adequate usage 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?

With no annotations, the description carries the transparency burden. It discloses the endpoint, implies a non-mutating list operation, notes the account-access scope, and enumerates the returned fields. It omits pagination and side-effect details, but this is adequate for a simple read-list tool.

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

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

Two compact sentences: the first states the operation and endpoint, the second lists return fields. 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?

The endpoint, scope, and returned fields are clear, and an output schema exists. However, the undocumented enterprise_id parameter is material to making correct calls, and there is no guidance on choosing this over related workspace tools. Adequate but with a clear 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 0% and the description never mentions the only parameter, enterprise_id. An agent cannot determine whether enterprise_id filters the results, whether it is required, or what the default of 0 means. The description adds no 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 names a specific verb and resource ('List all workspaces'), gives the exact endpoint, and the 'all' scope distinguishes it from singular workspace tools like docflow_get_workspace. An agent can clearly tell 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 makes the context clear: use this when you need all workspaces accessible to the current account. It does not explicitly contrast it with alternatives like docflow_get_workspace, but the scope is stated well enough to avoid confusion.

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

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

No annotations are provided, so the description carries the full burden. It discloses the endpoint and the failure-state trigger, but does not explain side effects of retrying (whether extraction re-runs, whether calls are idempotent, or what happens to already-processed files).

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

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

Two short sentences with the action and trigger condition front-loaded. Every clause earns its place; 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?

An output schema exists, so return values need not be described. However, both required parameters are undocumented in both schema and description, and there are no annotations, leaving a moderate gap for an otherwise simple 2-parameter tool.

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

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

Schema description coverage is 0%, so the description must compensate, but it never explains what task_ids or workspace_id represent. An agent can only weakly infer that task_ids identify the failed file-processing jobs, and workspace_id is entirely unaddressed.

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

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

States a specific verb+resource ('Retry processing for files that failed') plus the exact trigger condition (recognition_status=2), and names the HTTP endpoint (POST /file/retry). The 'files' target clearly differentiates it from the sibling retry tools docflow_retry_review_task and docflow_retry_review_rule.

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

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

Provides an explicit 'Use when recognition_status=2 (failed)' condition, which is clear usage context. It stops short of listing when not to use it or explicitly naming the review-retry siblings as alternatives, so it misses the top tier.

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

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

With no annotations, the description carries the full behavioral burden. It adds useful context about the retry being scoped to a single rule and not re-running other rules, but it does not disclose permissions, idempotency, whether previous results are overwritten, or what makes a rule retryable.

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

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

Two tightly written sentences. The action and endpoint are front-loaded, followed by precise usage context, with no redundant or filler content.

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

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

Given no annotations and zero schema-level parameter descriptions, some gaps remain: retryable rule states, error behavior, and whether a new review result is produced. The output schema covers return values and the input is simple, but the definition is not fully self-sufficient.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not explain the individual parameters or their relationships beyond the phrase 'single rule within a review task'. The IDs are self-explanatory by name, but the description adds no detail about formats, where to obtain them, or how they relate to other resources.

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

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

States a specific action ('Retry evaluation of a single rule within a review task') and gives the endpoint. The explicit scope qualifier 'single rule' distinguishes it from sibling docflow_retry_review_task, so an agent can tell them apart immediately.

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

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

Provides explicit when-to-use guidance: one specific rule failed or needs re-evaluation after updating its prompt. It also states the exclusion condition, 'without re-running all other rules in the task', which routes the agent away from task-level retry.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does reveal a meaningful behavior: 'All rules in the task will be re-evaluated.' However, it does not disclose whether the retry replaces prior results, requires an existing failed task, or has other side effects, leaving some behavioral ambiguity.

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

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

Two sentences, front-loaded with action and condition, followed by a concise statement of the retry scope. Every clause adds useful information without fluff or repetition.

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

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

For a low-complexity tool with two self-describing parameters and an output schema present, the description covers purpose, trigger, and behavioral effect. It is mostly complete, though it could be stronger by explaining the workspace_id parameter and explicitly routing single-rule retries to retry_review_rule.

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 never mentions workspace_id or task_id. The phrase 'entire review task' implies that task_id refers to a review task, but workspace_id is left entirely to inference, so the description does not compensate for the missing schema-level parameter documentation.

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

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

The description states a specific action and resource: 'Retry an entire review task' and adds the condition 'that failed or produced unexpected results.' The qualifier 'entire' and the note 'All rules in the task will be re-evaluated' clearly distinguish this from sibling tools like docflow_retry_review_rule and docflow_retry_files.

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 'failed or produced unexpected results' provides a clear trigger for when the tool should be used. However, it does not explicitly state when not to use it or point to alternatives such as retrying a single rule instead of the whole task, so it stops short of full exclusion guidance.

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

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

No annotations are provided, so the description carries the behavioral burden. It usefully discloses that the tool blocks by submitting and waiting for results, which is reinforced by the timeout parameter. However, it does not state what happens on timeout, whether the review task persists for later retrieval, or what side effects occur.

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 wasted words. The core verb, resource, and blocking behavior are all expressed immediately and clearly.

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 rich input schema and presence of an output schema reduce the burden on the description. Still, the description does not explain the surrounding workflow, timeout behavior beyond the schema default, or when to prefer docflow_get_review_result or docflow_retry_review_task. It is minimally 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 description coverage is 100%, and each parameter already has meaningful provenance descriptions such as 'from docflow_setup_review_rules' and 'from docflow_upload_and_extract.' The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific action ('Submit') and resource ('review task') and adds 'wait for results,' which distinguishes it from related siblings like docflow_get_review_result or docflow_retry_review_task. The title alone would not convey the blocking nature, but the description 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?

No when-to-use guidance is provided: no mention of prerequisites, exclusions, or alternatives such as docflow_get_review_result or docflow_retry_review_task. The only sequencing hints live in parameter descriptions, not in the tool description itself.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the important idempotent behavior ('reuses existing repo if name matches'), which is valuable. However, it doesn't explain what happens to the provided rule_groups when an existing repo is reused — whether they are applied, merged, or ignored — nor does it mention permissions or side effects beyond creation.

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

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

A single short sentence with zero filler. The core action and the key idempotent behavior are front-loaded. 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?

The output schema covers return values and the input schema covers parameters, so the main gap is behavioral context. The description leaves unclear what happens when a repository with the same name already exists but different rule_groups are passed — a materially ambiguous outcome for a mutating setup tool. It is adequate for simple use but incomplete for correct repeated invocations.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters in detail, including the rule_groups format. The description adds little beyond reinforcing the 'name matches' reuse concept for repo_name. The baseline of 3 applies because the schema does the heavy lifting.

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

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

The description clearly states a specific action ('Create a review rule repository') and a specific resource. It adds the idempotent reuse behavior, which helps define what the tool does. It doesn't explicitly differentiate from sibling tools like docflow_update_review_repo, but 'create' + 'repository' is specific 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?

The description gives no guidance on when to use this tool versus alternatives such as docflow_update_review_repo, docflow_update_review_rule_group, or docflow_list_review_repos. There is no mention of exclusions, prerequisites, or preferred conditions for selection.

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

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

No annotations are provided, so the description carries the full burden of disclosing behavior. It only repeats the update intent and endpoint, without mentioning side effects, permissions, idempotency, or consequences of changing settings. This is a significant gap for a mutation tool.

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

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

The description is a single, front-loaded sentence with no filler. The endpoint inclusion is useful, but the phrase 'settings' is somewhat generic and could have been used more specifically.

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

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

Given a mutation tool with no annotations, six parameters, and competing sibling tools, this description is too sparse. It omits usage context, behavioral details, and sufficient parameter semantics. The presence of an output schema helps but does not make up for the missing operational guidance.

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%, and the description adds no parameter-level meaning. It does not clarify that workspace_id and category_id identify the target, nor does it explain the meaning of name or the interaction between enabled, extract_model, and category_prompt. The schema itself provides descriptions for some fields, but the description fails to compensate for the remaining 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 states a specific verb and resource: 'update an existing file category's settings.' Including the endpoint ('POST /category/update') further clarifies the operation. However, it does not explicitly differentiate from the similar sibling docflow_amend_category, so it stops short of a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives such as docflow_create_category, docflow_amend_category, or docflow_delete_category. The word 'existing' implies it is not for creation, but there are no explicit context cues or exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool updates fields and adds a beneficial consequence of updating the prompt, but it does not mention whether updates are partial or full replacements, whether null values clear fields, what permissions are required, or any side effects. This is a significant transparency gap for a mutation tool.

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

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

The description is only two sentences and wastes no words. The core action and endpoint are front-loaded, followed by a single useful usage note. Every sentence contributes meaningful 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?

The tool has six parameters, no annotations, and an output schema, so the description does not need to explain return values. However, it omits important operational details such as update semantics, constraints on null values, and whether all three optional fields can be omitted. These gaps make it only minimally adequate 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 names three of the mutable parameters (name, description, prompt) and clarifies their purpose, but it leaves the three required identifier parameters (workspace_id, category_id, field_id) to be inferred from names. It also does not explain the nullable defaults or whether at least one optional field must be provided.

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 ('Update') and resource ('a field's name, description, or extraction prompt'), and includes the exact POST endpoint. This clearly distinguishes it from sibling update tools like docflow_update_category and docflow_update_category_table, which target different resources.

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

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

The description clearly implies when to use this tool: when you need to modify a category field's name, description, or extraction prompt. The second sentence adds a concrete motivating scenario ('improve extraction accuracy for specific field types'), providing useful context, though it does not explicitly discuss alternatives 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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only says 'Update', which is already implied by the name, without stating side effects, permissions, reversibility, output format, or any operational implications. This is a significant gap for a mutation tool.

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

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

The description is a single sentence, which is concise, but it is under-specified rather than pragmatic. It includes only the endpoint, offering no additional insight. This is closer to under-specification than effective conciseness.

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

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

For a mutation tool with no annotations and low schema coverage, this description is critically incomplete. It does not explain what 'table configuration' means, what fields are updatable, what happens after the update, or any operational context, leaving agents with insufficient information to call it correctly.

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

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

Schema description coverage is only 20% (only collect_from_multi_table has a description), and the description itself adds nothing about parameters, their semantics, defaults, or relationships. With such low coverage, the description should compensate but does not, leaving agents to guess about workspace_id, category_id, and table_id.

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 ('Update') and resource ('a table configuration in a category'), which clearly indicates the action. It is distinguishable from sibling update tools by focusing on 'table configuration', although it does not explicitly name alternatives or contrast with 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?

No guidance is provided on when to use this tool versus other update tools (e.g., docflow_update_category, docflow_update_category_field). There is no mention of prerequisites, specific scenarios, or alternatives, leaving the agent to infer usage from the name and parameters.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It indicates the operation is a mutation via 'Update' and 'POST', but it does not mention side effects, idempotence, allowed verification status values, permissions, or consequences for the file.

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

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

The description is a single front-loaded sentence with no filler. It states the action, the resource, the kinds of updates, and the endpoint 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?

The schema and output schema carry parameter and return-value details, so the baseline burden is lower. Still, because there are no annotations and no usage guidance, some important context around status updates and file prerequisites is missing, making the definition merely adequate.

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 descriptions already cover all three parameters at 100% coverage. The description adds the context that updates target 'metadata or verification status', but it does not meaningfully extend the per-parameter semantics already present.

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

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

The description uses a specific verb ('Update') with a precise object ('metadata or verification status of a processed file') and even includes the endpoint. This clearly distinguishes it from file-upload, fetch, delete, and retry siblings.

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

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

No guidance is given about when to use this tool versus alternatives like docflow_retry_files, docflow_run_review, or docflow_delete_files. The phrase 'processed file' implies a precondition, but there is no explicit when-to-use or when-not-to-use guidance.

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

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

No annotations are provided, so the description must carry the full behavioral burden. It only restates that the operation renames a repository and gives the endpoint; it does not disclose side effects, uniqueness requirements, permissions, validation behavior, or whether the rename is reversible.

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 focused sentence with the endpoint in parentheses. There is no redundant wording, and the core action is front-loaded.

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

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

For a mutation tool with no annotations, 0% parameter coverage, and no usage guidance, one sentence is insufficient. The output schema reduces the need to document return values, but the description still omits important context about when and 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 0%, so the description must compensate. It adds only that 'name' is the new name implied by 'Rename'; workspace_id and repo_id semantics are left entirely to inference from their 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 clearly states the action ('Rename') and the resource ('review rule repository'), and the endpoint gives a concrete reference. It is distinct from sibling tools like update_review_rule or update_review_rule_group, though it does not explicitly name those alternatives.

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

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

There is no guidance on when to use this tool versus alternatives such as list_review_repos, get_review_repo, update_review_rule, or delete_review_repo. The description implies use when renaming, but gives no context, prerequisites, or exclusions.

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

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

No annotations are provided, so the description carries full behavioral disclosure burden. It says the tool updates a rule's prompt or configuration, but it does not explain whether fields are merged or replaced, whether omitted optional fields are reset, what happens if the rule does not exist, or what side effects occur. For a mutation tool, this is a significant gap.

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

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

The description is three short sentences with no filler. It front-loads the core action and endpoint, then gives usage guidance and a key parameter mapping. Every sentence contributes value.

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

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

For a 7-parameter mutation tool with no annotations, the description is incomplete. It covers risk_level and general prompt/config updates, but key parameters such as category_ids and referenced_fields are left unexplained, and it does not clarify update semantics for optional fields. The output schema covers return values, but the input behavior is underspecified.

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 adds meaning for risk_level with enum values (10=high, 20=medium, 30=low), but it does not explain name, category_ids, referenced_fields, workspace_id, or rule_id semantics beyond their 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 states a specific action, 'Update an existing review rule's prompt or configuration,' and includes the endpoint. It is clearly differentiated from create/setup tools by the word 'existing,' though it does not explicitly name sibling tools.

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

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

The description provides concrete use cases: 'refine rule prompts based on review results, or adjust risk levels.' This gives clear context for when to invoke the tool, though it does not mention when not to use it or how it compares to alternatives.

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

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

No annotations are provided, so the description carries the full behavioral burden. It only states the rename action and endpoint, without disclosing whether the name is overwritten, whether existing settings are preserved, required permissions, or side effects.

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

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

The description is a single front-loaded sentence with no filler. The endpoint reference adds useful precision without bloat.

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 state-changing tool with three required parameters and no annotations, the description is too thin. It omits parameter semantics and behavioral caveats, and relies on the output schema to cover return-value expectations.

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 workspace_id, group_id, or name. The verb 'rename' hints that name is the new value, but the IDs and their role/scoping are left entirely to inference from parameter 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 states a specific verb ('Rename') and resource ('review rule group'), making it clearly distinct from sibling tools that update or delete review rules/groups. The endpoint reference reinforces the exact 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 usage is implied: use this when the goal is to rename a review rule group. However, it does not explicitly contrast with docflow_update_review_rule or docflow_delete_review_rule_group, so an agent gets no explicit when-not-to-use guidance.

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

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

With no annotations provided, the description bears the full burden but merely restates the action and HTTP method. It does not disclose side effects, whether unspecified fields are preserved or reset, permission requirements, or the meaning of passing null for optional fields. For a mutation tool, this is a significant transparency gap.

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

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

The description is a single sentence with no filler and places the core action first, followed by the endpoint in parentheses. It is appropriately terse and scannable, though it is minimal enough that the conciseness borderlines on under-specification.

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

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

The tool has five parameters, an output schema, and no annotations, but the description only states the action and endpoint. Missing are usage context, behavioral expectations, and clarification of null semantics for optional fields, leaving an agent to guess at important invocation details despite the rich 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?

The input schema has 100% description coverage for all five parameters, including workspace_id, name, auth_scope, description, and callback_url. The description itself adds no parameter-specific meaning beyond the generic word 'settings', so the schema legitimately carries the semantic load.

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 ('Update') and resource ('workspace settings'), making the tool's function unmistakable. The word 'workspace' distinguishes it from the many sibling tools targeting categories, files, and review rules, and 'update' separates it from get/delete/list workspace operations.

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

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

No guidance is given on when to use this tool versus alternatives such as docflow_get_or_create_workspace, docflow_get_workspace, or docflow_retry_files. The description only states the action; there is no mention of preconditions, exclusions, or fallback tools, leaving usage entirely to inference.

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

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

With no annotations, the description carries the full burden. It discloses that the call blocks until classification and extraction finish ('wait for... to complete') and enumerates supported formats. But it stays silent on side effects (files persist in the workspace), timeout/error behavior beyond the schema default, and how failures could be recovered via the retry siblings.

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, each earning its place: core behavior, input-mode rule, and format constraint. The main action is front-loaded, and there is zero filler or restatement of the title.

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

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

An output schema covers return values and all six parameters are fully documented, so those burdens are lifted. Still, for a complex async mutation with zero annotation coverage, the description omits side-effect disclosure, timeout consequences, and the retry path — an agent cannot predict what happens when processing fails or times out.

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

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

Schema coverage is 100%, baselining this at 3, but the description adds the either/or relationship between file_paths and directory ('Provide either...'), which is not expressible in the JSON schema. It also ties the supported-format list to what directory auto-scanning will pick up, giving an agent real selection guidance beyond the schema text.

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

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

The description opens with a specific verb+resource pair: 'Upload files and wait for classification and extraction to complete.' It names the two invocation modes (explicit file_paths or auto-scanning directory) and clearly differentiates this ingestion tool from the sibling set, none of which handle uploads. 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?

It explains how to choose between the file_paths and directory inputs ('Provide either...'), and the supported-format list lets an agent pre-filter files. However, it never states when to prefer this tool over siblings like docflow_extract_fields, docflow_retry_files, or docflow_fetch_files, and gives no exclusions. When-not-to-use guidance must be inferred from the tool's name alone.

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