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

No annotations are provided, so the description carries the full disclosure burden, and it discloses essentially nothing: no auth/permission requirements, no side effects, no uniqueness or validation behavior, no indication of what the response contains. For a 9-parameter mutating tool this is a serious gap.

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

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

A single short sentence with zero filler is technically concise and front-loaded, but here brevity is under-specification rather than efficiency. There is no wasted text, yet the sentence does not earn its place by conveying anything an agent could not infer from the name.

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

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

Given 9 parameters, two nested object parameters, no annotations, and no output schema, the description is far too thin to call this tool correctly. Nothing tells the agent how to populate configuration, whether connector_id is required in practice, or what a successful creation returns.

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

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

Schema description coverage is only 56% (status, connector_id, connector_configuration, description, executable_by_ai_agents are undocumented), and the description adds no parameter meaning at all. It does not explain the configuration vs connector_configuration alias, the relationship between status and is_active, or the role of executable_by_ai_agents.

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 nearly restates the tool name: 'Create' + 'integration' is exactly what tealfabric_create_integration encodes. It gives no scope detail (what an integration comprises, what is required, how it relates to connectors) and does nothing to separate it from siblings like tealfabric_update_integration or tealfabric_create_webapp.

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

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

There is no guidance on when to use this versus tealfabric_update_integration, tealfabric_execute_integration, or the connector tools. No preconditions, no mention that a connector_id may be needed first, and no statement of what happens if an integration with the same name already exists.

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

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

No annotations exist, so the description carries the full burden, yet it only discloses the return value (process_id). It says nothing about side effects of creation, what defaults get applied to unspecified fields, whether name must be unique, or whether the created process is immediately executable — all critical for a 9-param creation tool.

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

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

Two short sentences, zero filler, with the action stated first and the return value second. Nothing drags or buries the lede.

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 9 parameters, a nested free-form configuration object, no annotations, and no output schema, this description is far too thin. The only compensating element is the mention of process_id, leaving defaults, validation rules, and the shape of the configuration object undocumented.

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 11% across 9 parameters, and the description adds no meaning for any of them — not for type, category, priority, is_template, configuration, or executable_by_ai_agents, all of which are opaque bare types. The one sentence of description is entirely about the return value, so the large coverage gap goes uncompensated.

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 ("Create a new Tealfabric process") and parenthetically disambiguates the resource as a process flow. It is clearly distinct from siblings like update_process, delete_process, or execute_process by virtue of the create verb, though it never names those siblings explicitly.

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

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

There is no guidance on when to use this versus tealfabric_update_process or tealfabric_create_process_step, no mention of prerequisites such as required permissions or an existing workspace, and no exclusions. An agent must infer everything from the tool 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 the full burden. It discloses only the return value; it says nothing about where the new step is placed by default, how sequence/sequence_order conflicts are resolved, whether required fields like step_type default to 'action', or what permissions are needed for a mutation.

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

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

Two short sentences with the purpose front-loaded and zero filler. It is efficient, though the terseness tips into under-specification for a 13-parameter tool.

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

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

For a mutation tool with 13 params, nested object schemas, alias/duplicate fields, and no annotations, two sentences are far from sufficient. The stated return value partially helps since there is no output schema, but the parameter ambiguity and placement behavior are unaddressed.

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

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

Schema description coverage is only 31% across 13 parameters including nested objects, and the description mentions none of them. Critical ambiguities — the 'name' vs 'step_name' alias and the 'sequence' vs 'sequence_order' duplicate — are left completely unexplained, so the description compensates for nothing.

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 ('Create a new process step') plus the return value ('new step_id'), which is enough to distinguish it from tealfabric_update_process_step and tealfabric_delete_process_step. It does not, however, explain what a process step is or how it relates to the sibling process 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?

There is no guidance on when to use this versus tealfabric_update_process_step or tealfabric_create_process, no prerequisite that the parent process must already exist, and no note about ordering relative to other steps. The agent is left to infer all of this.

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

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

With no annotations, the description carries the full burden. It usefully discloses the 'unpublished by default' safe default state, but for a 22-param mutation tool it says nothing about auth setup requirements (auth_require/auth_transport), how public_uris/custom_security_policy behave, or what a successful response looks like.

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, front-loaded with the core purpose and the key default. No waste, though the second sentence adds little beyond the schema.

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

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

A complex 22-param creation tool with 23% schema coverage, no annotations, and no output schema demands far more than this. The description omits the bulk of parameter semantics, auth configuration behavior, and the publishing relationship to siblings.

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

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

Schema coverage is only 23%, so the description needs to compensate heavily. Instead it merely restates the four required params already declared in the schema's required array, and says nothing about the 18 optional params (custom_css, http_headers, public_uris, etc.) that an agent would struggle to set correctly.

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

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

States a specific verb+resource ('Create a new Tealfabric webapp'), which distinguishes it from list/get/update/delete siblings. However, it doesn't explicitly differentiate from the closely related tealfabric_create_webapp_version sibling, leaving a small 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?

The '(unpublished by default)' note hints at a publish workflow but never says when to use this vs create_webapp_version or publish_webapp, and gives no when-not conditions. An agent must infer the workflow entirely.

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

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

No annotations are provided, so the description carries the full burden. It does add real value by disclosing that the operation copies the latest version and that the result is unpublished (not live), but says nothing about permissions, whether the source webapp's state changes, or what the call returns.

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

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

One short sentence with the key constraint ('unpublished') and the copy behavior front-loaded. Nothing is wasted and nothing important is buried.

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

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

For a simple one-parameter create tool with no annotations or output schema, the description covers what it does but omits what the caller gets back (new version identifier?) and any precondition such as an existing version to copy. Adequate but with clear gaps.

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

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

There is a single parameter with 100% schema coverage ('Webapp UUID'), so the schema already carries the semantics. The description adds no further detail about the identifier (e.g., where to obtain it or that it refers to the source webapp being copied). Baseline 3 applies.

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

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

States a specific verb and resource ('Create a new ... version of a webapp') and scopes it with 'unpublished' plus the copy semantics in parentheses. It implicitly contrasts with tealfabric_create_webapp and tealfabric_publish_webapp, but never names those siblings, so an agent must infer the distinction.

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

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

The description implies the usage case (you want a draft copy of the current version before editing), but gives no explicit when-to-use/when-not guidance and no mention of alternatives such as create_webapp or update_webapp. Usage is inferred from the word 'unpublished' rather than stated.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about permanence, recoverability, or whether deleting a directory recursively removes its contents. For a destructive operation with zero annotation coverage, that is a substantial gap.

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

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

A single front-loaded sentence with no filler. It is efficient, though the space saved could have carried needed destructive-behavior caveats.

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, no-annotation, no-output-schema tool, the description leaves critical questions open: whether deletion is permanent, what happens to directory contents, and what the API returns. It is under-specified for the operation's risk profile.

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

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

Schema description coverage is 100%, with both path and the deprecated tenant_id already documented inline, so the baseline is 3. The description adds nothing beyond the schema, which is acceptable here given the schema does the work.

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

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

States a specific verb (delete) and resource (file or directory) scoped to Tealfabric documents storage, which an agent can distinguish from siblings like move_document or download_document. It stops short of naming the sibling it displaces, but the action 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?

No guidance on when to choose delete over alternatives such as move_document, nor any prerequisite or safety context. The agent must infer entirely from the name that this is the removal operation for documents.

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 says only 'Delete', with no disclosure of irreversibility, required permissions, cascade effects on dependent data, or behavior when the ID does not exist — all critical for a destructive mutation.

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

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

A single front-loaded sentence with zero waste. It is concise to the point of under-specification, but structure is not a problem.

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 no output schema, the description is far too thin. It omits irreversibility, error behavior on invalid IDs, and side effects, leaving the agent without the context needed to call it safely.

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

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

Only one parameter exists and schema description coverage is 100%, so the schema already documents 'integration_id'. The description's 'by ID' adds nothing beyond that, 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?

The description states a specific verb and resource (delete an integration) with scope ('by ID'), which distinguishes it from the create/update/list/execute siblings. It stops short of explicitly naming those alternatives, so 4 rather than 5.

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

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

There is no when-to-use guidance, no preconditions, and no mention of alternatives such as update or list_integrations. The agent must infer everything from the tool name.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Hard-delete' is a genuine value-add, disclosing permanence/irreversibility that annotations would otherwise signal via destructiveHint. However, it omits cascading effects (does deleting a process also delete its steps?), required permissions, and any confirmation/error behavior.

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

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

One short sentence, front-loaded with verb and resource, zero filler. No restructuring needed.

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?

Adequate for a simple one-parameter destructive tool with no output schema, but it leaves out cascade semantics and permissions — details that matter specifically for an irreversible delete and that annotations would otherwise cover.

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

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

Only one parameter, and schema description coverage is 100% with process_id documented. The description adds no syntax or format detail beyond the schema, but with a single fully-documented identifier the baseline of 4 applies.

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

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

States a specific verb (hard-delete), resource (Tealfabric process) and selector (by ID). The qualifier 'hard' implicitly separates it from the sibling tealfabric_retire_process (soft retire) without naming it, so an agent can mostly 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?

No explicit when-to-use or when-not guidance. The word 'hard-delete' hints that this is the permanent option versus tealfabric_retire_process / tealfabric_delete_process_step, but the agent must infer that contrast rather than being routed to 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 does not say the deletion is irreversible, what happens to a step referenced by a running process, whether dependencies/child references are cleaned up, or what permissions are required — all critical for a destructive operation.

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

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

One short sentence with the target and key front-loaded and zero filler. Nothing is padded or redundant.

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

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

For a destructive, unannotated tool with no output schema, the definition says nothing about failure modes, cascade effects, or confirmation semantics. The agent has no basis to predict what a successful or failed call looks like.

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

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

Schema coverage is 100% with a single required string parameter, so the schema already documents step_id. The description only restates the identifier without adding format, source, or caveats (e.g., where to obtain the step_id). Baseline 3 applies.

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

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

States a specific verb (Delete) and resource (process step) and the lookup key (step_id). It is clearly distinguishable from create_process_step/update_process_step/get_process_step. It stops short of naming those siblings explicitly, so it settles at 4 rather than 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 gives no guidance on when to delete versus retiring a process or updating a step, and no prerequisites or warnings. An agent must infer entirely from the tool name which of the many process-step siblings to call.

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, yet it discloses nothing beyond the verb. It doesn't say whether the deletion is permanent, whether published versions are removed with it, whether a confirmation or special permission is required, or what happens to a webapp that is currently published.

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

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

One short, front-loaded sentence with no filler. It is efficient but borders on under-specified rather than truly 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 an irreversible mutation with zero annotation coverage and no output schema, the definition is too thin. An agent cannot tell what success looks like, whether the action cascades, or how it differs from unpublishing.

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 full coverage of the single webapp_id parameter, and its description states it is a UUID. The tool description adds only 'by ID', which confirms the resource is identified by that field but adds no format or sourcing detail beyond the schema.

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

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

States a specific verb and resource (delete a Tealfabric webapp) plus the identifier used. It distinguishes 'delete' from siblings like tealfabric_update_webapp, though it does not distinguish it from tealfabric_unpublish_webapp, which is the nearest 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?

No guidance on when to use this versus tealfabric_unpublish_webapp or tealfabric_delete_process, and no prerequisites such as ownership or permissions. The only cue is the verb itself, leaving the agent to infer the destructive path.

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 does disclose the return encoding (base64) and that the transfer is binary-safe, which is real behavioral value. It is silent on permissions/auth scope, size limits, and what happens when the path doesn't exist – notable gaps for a read of arbitrary storage paths.

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

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

Two short sentences, zero waste, with the return-format detail front-loaded immediately after the action. Nothing to trim.

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

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

There is no output schema, so the base64 note usefully covers the return value, and only one required parameter keeps the surface small. However, for a storage-fetch tool it omits error behavior (missing file, permission denied) and whether paths are tenant-relative, leaving an agent without expectations for failure cases.

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

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

Schema coverage is 100% and the file_path example ('packages/report-v1.zip') already establishes the path format, so the schema does the heavy lifting. The description adds no further semantics about path resolution or the ignored tenant_id, so baseline 3 applies.

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

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

States a specific verb and resource ('Download a document/file from Tealfabric documents storage') and adds the return encoding. It doesn't explicitly distinguish itself from the closest siblings tealfabric_read_document_text or tealfabric_upload_document, so an agent must infer that this is the binary counterpart to the text reader.

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

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

Usage is implied by 'document/file' and 'base64 for binary-safe transfer', which hints at binaries rather than text, but there is no explicit when-to-use or 'use read_document_text for plain text instead' routing statement despite that sibling existing.

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

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

No annotations are provided, so the description carries the full disclosure burden, yet it never says what execution actually does: whether it fires an outbound call to a connected system, whether it has side effects, whether it is retryable, or what happens on failure. The async flag is mentioned but its semantics (queued, returns immediately, no result) are not explained.

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?

It is a single front-loaded sentence with no padding, but the brevity comes at the cost of substance rather than being efficient compression. Nothing is wasted, yet almost nothing is contributed.

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 side-effecting execution tool with no annotations and no output schema, the description should cover return shape, failure behavior, and async implications. None of that is present, leaving the agent materially under-informed before invoking.

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

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

Schema coverage is 100%, so the schema already documents integration_id, data, and async. The description adds no meaning beyond restating 'optional async' and 'optional call data', which is the baseline expectation when the schema does the work.

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

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

The description names a verb ('Execute') and resource ('integration'), but 'Execute an integration' essentially restates the tool name tealfabric_execute_integration. It does not distinguish this tool from sibling tealfabric_execute_process or tealfabric_test_connector, so an agent cannot tell which execution entry point applies to which object type.

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

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

There is no guidance on when to use this versus tealfabric_execute_process or tealfabric_test_connector. The parenthetical '(optionally async)' hints at a choice, but it is not framed as a decision rule for the caller.

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

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

No annotations are provided, so the description carries the full burden: it does not say whether execution is synchronous or asynchronous, what side effects occur in downstream connectors, whether it is idempotent, or what a failure looks like. Only the 'optional input' detail hints at behavior at all.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though the brevity is a function of under-specification rather than precision.

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

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

For a tool with a free-form nested input payload, no output schema, and zero annotations, the description omits what execution returns, whether results are polled, and how the input object maps to process variables. The agent is left guessing about the most consequential aspects of the call.

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

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

Schema description coverage is 100%, so both process_id and the nested input object are already documented in the schema; the description's 'optional input' only restates the optionality. Baseline 3 applies since the schema does the heavy lifting, though the free-form nature of the nested input object is not elaborated anywhere.

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 (Execute) and resource (a Tealfabric process), so the basic action is clear. But it does nothing to distinguish this from the many sibling tools that also 'execute' or 'run' things (e.g. tealfabric_execute_integration), and 'Tealfabric process' just echoes the namespace rather than explaining what a process is.

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

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

There is no guidance on when to use this versus tealfabric_execute_integration, tealfabric_get_process, or tealfabric_list_processes, and no prerequisites (permissions, process state, whether steps must exist). The agent has to infer everything about appropriate invocation 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 the full behavioral burden. It implies a non-mutating check via 'Check whether', but does not state what happens if the connector_id is unknown/invalid, or what the answer looks like (boolean field name). For a trivial read-only predicate this is acceptable but not rich.

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

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

One front-loaded sentence with zero filler; every word contributes to identifying the operation.

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

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

For a one-parameter boolean-style query with no output schema, the description conveys enough to invoke correctly. The remaining gap is that it does not explicitly describe the return value (a boolean flag), which would matter since no output schema exists.

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

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

There is a single parameter with 100% schema coverage, so the schema already documents connector_id. The description adds no extra semantics such as accepted ID formats or where to obtain a connector_id (e.g., from tealfabric_list_connectors), so baseline 3 applies.

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

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

The description uses a specific verb ('Check whether') plus a precise resource ('a connector requires OAuth2 authentication'), which is unambiguous about the operation. It does not name or differentiate from siblings such as tealfabric_test_connector, which sits closest to it in purpose.

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

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

The predicate phrasing implies a pre-flight check (e.g., before configuring or testing a connector's auth), but the description never states when to call it, when not to, or how it relates to tealfabric_test_connector or the integration tools. Usage is only inferable.

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 disclosure burden. It only implies a read operation and does not state permission requirements, behavior for missing files, or what metadata is returned.

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

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

The description is a single front-loaded sentence with no wasted text. It is appropriately concise, though it lacks any additional structure or differentiating 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?

With no annotations, no output schema, and no description of returned metadata or error behavior, the definition is too thin for an agent to understand the tool's full behavior. The parameters are well documented, but the description does not compensate for the missing behavioral context.

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%, including the required file_path and the optional tenant_id parameter. The description adds no parameter-level meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

It states a specific verb ('Get') and resource ('metadata for a document/file'), making the basic operation clear. It does not explicitly differentiate itself from sibling tools such as tealfabric_read_document_text, tealfabric_list_document_tree, or tealfabric_download_document.

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 related document tools. It does not mention alternatives, prerequisites, or exclusions, so an agent must infer selection from the tool 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 the full behavioral burden. 'Get' implies a read-only operation, but the description does not disclose permission needs, error behavior when the ID is not found, or what is returned beyond the resource name.

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

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

A single front-loaded sentence with no redundant or filler content. For a simple getter, this is appropriately sized.

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

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

The tool is simple, the schema fully covers the only parameter, and the description states the core action. However, with no annotations and no output schema, the description could reasonably say more about what a successful response contains or what happens on a missing 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 100%, so the single parameter is fully documented in the schema already. The description only repeats that it takes an ID and adds no format, validation, or source guidance beyond the schema.

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

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

States a specific verb ('Get') and resource ('a single Tealfabric process') with the scope clarified by 'by ID.' It implicitly distinguishes itself from list_processes, but does not explicitly name or differentiate from 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?

Provides no explicit when-to-use guidance or alternatives. The description implies the tool is used when a process ID is known, but does not say when to prefer it over list_processes or get_process_step.

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, and it discloses nothing beyond the read itself. It says nothing about what happens if the step_id is invalid or missing, whether permissions or process scoping apply, or what the response contains.

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

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

A single short sentence with the resource and lookup key front-loaded and no wasted words. It is efficient but so terse that it borders on under-specification rather than optimal concision.

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

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

The tool is simple (one required param, no nesting), but with no output schema and no annotations, the description should at least sketch the returned step shape or failure behavior. As written, an agent knows only the name, the key, and that it is a lookup.

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

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

Schema description coverage is 100%, so the single step_id parameter is already documented structurally; the description only repeats "by step_id". It adds no format, sourcing, or example detail, which is the expected baseline when the schema does the work.

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

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

The description states a specific verb ("Get") and resource ("a single process step") plus the lookup key (step_id), which clearly separates it from list_process_steps. It stops short of naming any sibling explicitly, so differentiation is inferred from "single" rather than stated.

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

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

Usage is only implied: an agent can infer it should be called when a step_id is already known and the full list is not needed. There is no explicit when-to-use, no exclusion, and no pointer to tealfabric_list_process_steps as the 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?

No annotations are provided, so the description carries the full behavioral burden. It hints at one useful behavior — that omitting version returns a default (presumably current) version — but says nothing about read-only safety, error behavior for unknown webapp_id or version, or permission requirements.

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

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

Two short sentences, zero filler, with the primary resource lookup front-loaded and the optional parameter noted second. Nothing is redundant or buried.

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

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

For a two-parameter read tool with full schema coverage and no output schema, the definition covers what an agent needs to invoke it. The only real gap is what the returned object looks like and whether omitting version truly means 'latest/current' — worth one clarifying clause.

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

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

Schema description coverage is 100%, so both parameters are already documented ('Webapp UUID', 'Version number (optional)'). The description restates the optionality of version but adds no format, range, or default-version semantics beyond the schema; baseline 3 applies.

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

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

The description states a specific verb and resource ('Get a single Tealfabric webapp by ID'), which an agent can immediately match to the list_webapps/get_webapp pair. It does not explicitly name the sibling it differs from (list_webapps, get_process), but the singular-resource framing makes the distinction obvious.

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

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

Usage is only implied: 'by ID' suggests this is the lookup path once an ID is known, versus tealfabric_list_webapps for discovery. There is no explicit when-to-use/when-not statement, no prerequisite (e.g., must the webapp be published?), and no mention of alternatives.

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

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

No annotations are provided, so the description carries the full disclosure burden, yet it does not state that this is read-only, whether connector parameters may expose sensitive values, or what permission/error behavior applies. The safe-read nature is only inferred from the listed operations.

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

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

A single front-loaded sentence lists the three supported modes with no filler. Each clause maps directly to an available operation.

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

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

For a low-complexity, two-parameter read tool with full schema coverage, the description covers the available operations adequately. However, with no annotations and no output schema, it could have confirmed read-only behavior and hinted at what connector parameters return.

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 action enum and connector_id already document parameter usage. The description only adds a high-level mapping of list/get/parameters modes and no extra syntax, defaults, or constraints.

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 resource (Tealfabric connectors) and three specific operations: list, get, and fetch parameters. It does not explicitly distinguish itself from connector siblings such as tealfabric_get_connector_oauth2_required or tealfabric_test_connector.

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 enumerates the three supported modes, but the actual selection logic is left to the schema's action enum and connector_id description. No when-not guidance or sibling alternatives are stated.

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

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

No annotations are provided, so the description carries the full disclosure burden. 'List' implies read-only, but nothing is said about pagination, result limits, whether the listing is recursive, or what a missing path does. For a listing tool that could return unbounded results, this is a meaningful gap.

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

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

Two compact sentences with the purpose front-loaded and no filler. It is arguably slightly under-written rather than verbose, but structurally there is no waste.

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

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

This is a simple two-parameter read tool with no nested objects, so a short description is defensible. Still, with no output schema and no annotations, the agent gets no picture of result shape, pagination, or ordering, and no disambiguation from the document-tree sibling.

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

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

Schema description coverage is 100%, and the schema's own description of `path` even explains the root default and gives an example. The description adds nothing beyond that, so baseline 3 applies.

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

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

States a specific verb and resource: 'List documents/files in a Tealfabric documents directory.' An agent knows exactly what it returns at a high level. It does not, however, distinguish itself from the nearby tealfabric_list_document_tree, which an agent could easily confuse it with.

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

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

'Use for browsing package files' gives a concrete context cue, but there is no explicit when-not guidance and no mention of the obvious alternative (list_document_tree for hierarchical traversal vs this flat directory listing). The agent must infer the distinction.

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, so the description carries the full burden, yet it discloses almost nothing behavioral: no confirmation this is read-only, no note that path defaults to some root, no mention that results are bounded by max_depth, and no explanation of the tree return shape. The tenant_id quirk (ignored by API) is only in the schema, not the description.

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. Brevity is appropriate for a simple list tool, though the '(action=tree)' clause is vestigial noise rather than value.

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

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

For a simple read-only listing, the description plus schema cover the call mechanics adequately. But with no output schema and no annotations, the agent gets no information about what a 'tree' response looks like (nested nodes vs paths) or how depth truncation is represented.

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

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

Schema coverage is 100% and each parameter is documented with defaults and ranges, so the schema does the heavy lifting. The description adds no parameter meaning beyond the word 'tree', meriting the baseline 3.

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

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

States a clear verb+resource: lists a documents directory as a tree. The '(action=tree)' parenthetical hints at scope but references an action parameter that does not exist in the schema, which adds slight noise. It is distinguishable from sibling tealfabric_list_documents only implicitly via 'as a tree'.

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

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

No when-to-use guidance, no exclusions, and no reference to the closest sibling (tealfabric_list_documents) or to tealfabric_get_document_metadata. The only implied guidance is that you'd want a hierarchical view, which the agent must infer.

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 and does not meet it. It does not state that the surface is read-only, that 'test' performs a live connection check with side effects, that execution-history is paginated by limit, or what permissions are required. 'test' in particular is a non-obvious action an agent could invoke unsafely without a 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?

It is a single compact sentence with no padding, which is good, but the slash-delimited list of modes is compressed to the point of ambiguity and nothing is front-loaded about the action-driven design. Efficient but under-informative.

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 12-parameter, five-mode tool with no annotations and no output schema, the description should explain mode selection, parameter requirements per mode, and return shape. It supplies none of these, leaving the agent to reverse-engineer behavior from a partially described schema.

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

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

Schema coverage is only 42% with 12 parameters, so the description must compensate and does not. It never explains the action-to-parameter pairing (integration_id for get/test/execution-history, execution_id for status), nor the seven undocumented params (page, type, search, status, sort_by, sort_direction, items_per_page). Only the schema's own 'action' and 'limit' descriptions carry any semantics.

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

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

The description names the primary resource (integrations) and lists the supported query modes (details/status/statistics/execution history), but 'via action filters' is vague and it never says this is a single multi-mode dispatch tool driven by the action enum. An agent can guess it is a read/list surface, but the boundaries between modes are fuzzy.

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

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

No guidance on when to pick this tool over siblings such as tealfabric_execute_integration or tealfabric_update_integration, and no indication of which mode substitutes for a missing get_integration. The only usage hint ('via action filters') is a restatement of the enum in the schema rather than actionable routing advice.

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 results are tenant-scoped and that authentication is required, and 'List' implies a read-only operation. However, it says nothing about pagination, result limits, ordering, or what happens with large tenants.

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

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

A single sentence with no filler, front-loading the verb, resource, and scope. Every word earns its place.

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

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

For a simple zero-parameter list tool this is close to adequate, but with no output schema the description does not say what is returned (e.g., IDs, names, pagination tokens) or whether the full list is always returned. That leaves a meaningful gap for an agent preparing to call it.

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

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

The tool takes zero parameters, and the schema is empty with 100% coverage. There is nothing extra for the description to explain, so the baseline of 4 applies.

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

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

The description gives a specific verb ('List') and resource ('Tealfabric ProcessFlow processes') with a scope ('for the authenticated tenant'). It is clear enough to distinguish from get_process or list_process_steps, though it does not explicitly name 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 siblings like tealfabric_get_process or tealfabric_list_process_steps. The listing intent is implied, but no conditions, exclusions, or alternatives are stated.

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

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

No annotations are provided, so the description carries the full burden. It implies a safe read but says nothing about ordering of returned steps, pagination, permissions, or whether inactive/retired steps are included.

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

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

One short, front-loaded sentence with no waste. It is appropriately sized for a simple list tool, though it could have used the space for a routing hint.

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 read tool with full schema coverage, the essentials are present. But with no annotations and no output schema, the description should say more about what a returned step looks like and whether results are bounded or ordered.

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

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

Schema coverage is 100% and the single process_id parameter is fully documented in the schema. The description adds no meaning beyond that, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource ('List process steps') scoped to 'a given process', which is clearly distinct from create/update/delete step siblings. It does not distinguish itself from tealfabric_get_process_step or explain how listing relates to tealfabric_list_processes, so it stops short of a 5.

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

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

No guidance on when to use this versus tealfabric_get_process_step (single step) or tealfabric_list_processes. The only implied usage is 'you need the steps for a process,' which an agent could infer 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?

With no annotations, the description carries the full burden. It discloses tenant scoping (useful), but says nothing about pagination defaults, sort defaults, whether unpublished apps are included, result shape, or read-only safety. For an 8-parameter listing endpoint this is a notable gap.

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

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

One sentence, front-loaded and free of filler. However, the brevity reflects under-specification rather than disciplined economy given the tool's complexity.

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?

A listing tool with 8 optional filters, no annotations, no output schema, and almost no schema descriptions needs the description to explain filtering, sorting, and pagination behavior. None of that is present, leaving the agent to guess.

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

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

Schema coverage is only 13% (just 'search'), leaving page, type, sort_by, process_id, items_per_page, published_only, and sort_direction undocumented. The description adds no parameter meaning whatsoever, failing to compensate 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?

Clear verb+resource ('List Tealfabric webapps') and scope ('for the authenticated tenant'). It does not distinguish itself from siblings like tealfabric_get_webapp or explain when a listing is preferable to fetching a single app, keeping it below a 5.

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

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

There is no guidance on when to use this tool versus tealfabric_get_webapp, nor on how to use the filters or pagination. Usage is only implied by the verb 'List'.

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, and it discloses little beyond implying mutation. It does not state what happens if new_path already exists (overwrite? error?), whether the source must exist, whether moves across directories are permitted, or whether the operation is reversible. For a filesystem-style move with no annotation coverage, these are material gaps.

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

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

Two short sentences with the action and the resource front-loaded, and no filler. It is efficient, though the brevity contributes to the behavioral gaps noted elsewhere rather than being purely a virtue.

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

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

There is no output schema and no annotations, and this is a mutating operation, so the description should cover failure and overwrite semantics. It covers the what but not the what-happens. Given only three parameters and full schema coverage, an agent could still call it, but not predict its edge-case behavior.

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

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

Schema description coverage is 100%, so both required paths and the ignored tenant_id are already documented in the schema. The description's mention of 'package paths' adds only faint context and no syntax, format, or relative-vs-absolute path guidance. Baseline 3 applies when the schema does the work.

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

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

The description names a specific verb pair and resource: 'Move or rename a file/directory in Tealfabric documents storage.' That clearly distinguishes it from sibling operations like write_document_text, upload_document, or delete_document by name alone. It stops short of naming the siblings it is not, which keeps it from 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 phrase 'Use to update package paths or reorganize' gives a concrete scenario, which is more than nothing. However, it offers no exclusions or alternatives — an agent cannot tell from the text whether to use this versus upload_document plus delete_document, or how it interacts with document text writes. Usage is implied rather than prescribed.

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-disclosure burden. It states the publish effect ('make that version live'), but does not disclose reversibility, permission requirements, impact on an already-live version, or other operational traits of this mutating action.

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

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

The description is a single front-loaded sentence with no wasted words. It states the action and its practical effect 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?

The purpose and both parameters are clear, and no output schema exists to require return-value explanation. However, for a mutating publish operation with no annotations, the description should say more about operational consequences and prerequisites.

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

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

Schema coverage is 100%, and both required parameters (webapp_id, version) are documented in the schema. The description adds no parameter-level semantics beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Publish') and resource ('Tealfabric webapp version') and clarifies the effect with '(make that version live).' This distinguishes it reasonably from version-creation and update siblings, though it does not explicitly name alternatives.

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

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

The description implies the tool makes an existing version live, but gives no explicit when-to-use guidance, prerequisites, or comparison to siblings such as tealfabric_create_webapp_version, tealfabric_update_webapp, or tealfabric_unpublish_webapp.

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. 'Read' clearly signals a non-mutating operation and 'UTF-8 text' scopes what files are eligible, but there is no mention of permissions, size limits, or error behavior on missing 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?

A single front-loaded sentence with no padding. The trailing '(action=read-text)' is internal API plumbing that adds little for an agent, keeping it just short of a 5.

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

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

For a simple two-parameter read tool with full schema coverage, the description is sufficient to call it correctly. The only gap is that no output schema exists and the description does not say what the returned text looks like (raw string vs structured payload).

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%, including the useful note that tenant_id is ignored in favor of the auth tenant, so the schema already does the heavy lifting. The description adds no extra meaning about file_path format or path resolution.

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

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

States a specific verb and resource ('Read a UTF-8 text document from Tealfabric documents storage') with a format constraint. It implicitly distinguishes itself from tealfabric_write_document_text by the read verb, but never explicitly names siblings like tealfabric_download_document or tealfabric_get_document_metadata.

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

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

No when-to-use or when-not-to-use guidance is given. The agent must infer from the name that this is for text content rather than metadata (get_document_metadata) or binary retrieval (download_document); nothing in the description routes it explicitly.

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

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

No annotations exist, so the description carries the full burden, and it does disclose the concrete side effects (status change plus name prefixing) rather than just saying 'retire'. It omits reversibility/restore path and whether the operation is idempotent for an already-retired process, which matters for an unannotated mutation tool.

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

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

Two sentences, zero filler, with the effect disclosed first and the decision guidance second. 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 single-param unannotated mutation with no output schema, the description covers what changes and which alternative to prefer. Remaining gaps are restore/reversibility and confirming behavior on an already-inactive 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?

Only one parameter (process_id) and schema description coverage is 100%, so the schema already handles it fully. The description adds no extra meaning about ID format or source, which is the baseline expectation at high coverage.

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

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

States a specific verb and resource ('Soft-retire a process') and immediately defines the mechanism (status set inactive, name prefixed with '<retired>'). This clearly separates it from tealfabric_delete_process, which is the sibling it implicitly contrasts against.

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

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

Gives an explicit selection rule: 'Prefer this over hard delete when preserving history.' The alternative and the condition that favors this tool are both stated. It stops short of naming when-not-to-use cases or what to do if the process is already retired, 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?

No annotations are provided, so the description carries the full disclosure burden and says almost nothing. It does not state whether the test is a dry-run validation or actually exercises an external connection, whether it is idempotent, what could fail, or what a result looks like — all of which matter for a tool that likely performs outbound network calls.

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

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

A single front-loaded sentence with no filler. It is efficient, though some of the brevity reflects missing content rather than disciplined editing.

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

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

For a tool with a nested configuration object, no output schema, and zero annotations, the description should explain what a successful vs. failed test returns and any prerequisites. It says none of this, leaving the agent unable to predict the result or the side effects.

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

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

Schema description coverage is 100%, so both connector_id and the nested configuration object are documented in the schema itself. The description adds no meaning beyond that — it does not say which fields the configuration needs or how errors from a malformed configuration are surfaced. Baseline 3 applies.

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

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

States a specific verb ('Test') and resource ('a connector configuration') with the target endpoint named. However, 'test' is ambiguous — it could mean static schema validation or a live connectivity/auth probe — and the description does nothing to distinguish which.

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 at all: nothing about whether the connector must already exist, whether it must come before create_integration/update_integration, or when to consult the sibling get_connector_oauth2_required first. The agent has to infer the workflow placement entirely.

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

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

No annotations are provided, so the description carries the full burden, yet it says nothing about reversibility, whether the public URL stops resolving, idempotency, or what error occurs if the webapp is already offline. "Take it offline" hints at effect but doesn't confirm it, which is thin for a state-changing 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?

One short sentence, front-loaded with the verb and resource, with the parenthetical clarification placed where it reads naturally. Nothing extraneous.

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 tool with full schema coverage and no output schema, the description is minimally sufficient to call it correctly. But with zero annotations on a mutation, it should say more about the resulting state and failure modes.

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

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

There is a single parameter (webapp_id) with 100% schema description coverage ("Webapp UUID"), so the schema already does the work. The description adds nothing about the identifier beyond what is in the schema, matching the baseline for high-coverage schemas.

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 (unpublish) and resource (Tealfabric webapp), plus a clarifying gloss ("take it offline") that removes ambiguity about what unpublishing means. It's distinguishable from sibling tealfabric_delete_webapp by implication, but the description never explicitly contrasts the two.

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

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

Usage is only implied by the name's inverse relationship to tealfabric_publish_webapp; there is no explicit statement of when to choose unpublish over delete or update. No prerequisites, no note about whether the app must currently be published.

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, yet it discloses nothing: not whether this is a partial or full-replacement update, what happens to configuration when connector_id changes, whether changes are reversible, or what permissions are required. For a mutation tool with 10 parameters and zero annotation coverage, this is a critical 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 single sentence contains no waste but is under-specified rather than concise; brevity here is a symptom of missing content, not of efficient packaging. There is no front-loaded structure because there is only one tautological clause.

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

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

A 10-parameter mutation tool with nested objects, two enums, no annotations, and no output schema demands substantial description, and this one supplies a single sentence. An agent could not call this tool correctly without inspecting the schema and guessing at update 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 10 parameters at 10% schema description coverage (only integration_id is documented in the schema), the description must compensate and supplies nothing about name, type, status, is_active vs status, configuration, connector_id vs connector_configuration, or executable_by_ai_agents. The ambiguity between overlapping fields like status and is_active is left entirely unresolved.

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 restates the tool name almost verbatim ('Update an existing integration'), adding only the word 'existing'. It does not say what aspects of an integration can be updated or how this differs from tealfabric_create_integration or tealfabric_delete_integration beyond the obvious verb.

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

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

No guidance on when to choose this tool versus create/delete/list integration siblings, and no prerequisites (e.g., needing an existing integration_id, or that the integration must not be running). The agent is left to infer everything from the tool name.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure, yet it says nothing about permissions, partial versus full update semantics, side effects on process steps, reversibility, or required role. For a mutation tool with ten parameters, this is effectively no behavioral context beyond the verb 'Update'.

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 single sentence is concise, but for a ten-parameter mutation tool it is under-specified rather than appropriately concise. Brevity here removes information the agent needs instead of sharpening the message.

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 complex update operation with ten parameters, only one required parameter, no annotations, no output schema, and 10% schema coverage, the description is far too thin to guide correct invocation. It omits parameter meaning, behavioral constraints, and expected outcomes.

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 10%, with just process_id documented in the schema, and the description adds no meaning about the other nine parameters such as status, configuration, is_template, or executable_by_ai_agents. It does not compensate for the coverage gap at all.

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 ('Update') and resource ('Tealfabric process'), with a parenthetical clarifying that it is a process flow. It does not distinguish this tool from sibling update tools such as tealfabric_update_process_step or tealfabric_update_webapp, so the agent gets purpose but not sibling differentiation.

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

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

The description gives no guidance on when to use this tool versus alternatives such as tealfabric_create_process, tealfabric_update_process_step, or tealfabric_retire_process. It also omits preconditions or exclusions, 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?

No annotations are provided, so the description carries the full behavioral-disclosure burden. It implies a mutation but does not state permissions required, whether the update is partial or full replacement, side effects, reversibility, or how unspecified fields are handled.

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

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

The description is a single front-loaded sentence with no filler or redundancy. It is efficient, though it is too thin for a complex 15-parameter mutation tool.

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

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

Given 15 parameters, low schema description coverage, nested objects, no annotations, and no output schema, this one-sentence description is not complete enough. An agent would lack critical guidance for invoking the update correctly.

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

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

The tool has 15 parameters with only 27% schema description coverage, and the description mentions none of them. It adds no meaning about step_id, aliases like step_name, nested configuration, execution_timeout, or the update semantics of individual fields.

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

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

The description gives a clear verb and resource: update an existing process step in a process flow. It is understandable without opening the schema, but it does not distinguish this tool from nearby siblings such as create_process_step, delete_process_step, or update_process.

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 create_process_step, delete_process_step, or update_process. It also omits prerequisites or conditions for updating an existing step.

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 identifies this as a mutation, but does not state whether updates are partial or full, what happens to omitted fields, whether permissions are required, or what the response contains.

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

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

The description is a single front-loaded sentence with no wasted filler. However, the trailing 'etc.' is uninformative and the brevity is more under-specification than efficient concision for a 22-parameter mutation tool.

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

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

Given the high parameter count, no annotations, no output schema, and near-zero schema description coverage, the description is far too sparse. An agent would not know how to safely perform or scope the update.

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 9% across 22 parameters, so the description must compensate. It mentions broad categories (content, auth, public URI) but leaves most parameters, including auth_transport, version, custom security settings, and headers, unexplained.

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: update an existing Tealfabric webapp. The parenthetical gives example update areas, though only vaguely, and the tool is distinguishable from create/delete siblings by 'update an existing'.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as create_webapp, publish_webapp, or create_webapp_version. Usage is only implied by the word 'update'.

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, and it mostly repeats the schema's note that the file keeps its original name. It says nothing about overwrite/conflict behavior when a file of that name already exists, size limits, required permissions, or what the call returns after upload.

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

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

Two short sentences, front-loaded with the action and followed by the use case; no filler. Minor redundancy between 'documents storage' and the restated name behavior keeps it off a 5.

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

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

With only three parameters, two required and one documented as ignored, the description is adequate to attempt a call. But for a mutation tool with no annotations and no output schema, it omits the post-call picture: overwrite semantics, error conditions, and whether anything is returned.

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%, including the unusual 'tenant_id is ignored by the API' caveat, so the schema already does the parameter work. The description adds no syntax, format, or validation detail beyond restating that the stored name comes from the uploaded file.

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 ('Upload a file to Tealfabric documents storage') and adds a concrete use case ('publish built package files for delivery'), which separates it from read/list siblings. It does not explicitly distinguish itself from tealfabric_write_document_text or tealfabric_move_document, so an agent still has to infer that this is the binary-upload path.

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

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

'Use to publish built package files for delivery' gives one implied scenario, which is more than nothing. However, there is no guidance on when to prefer this over write_document_text, no exclusions, and no stated prerequisites (auth tenant, destination directory must exist).

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

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

No annotations are supplied, so the description carries the full burden. It does disclose one genuinely useful behavior — that a backup is created — but says nothing about whether an existing file is overwritten, whether a missing parent path is created, what auth/permissions are required, or what is returned on success. That leaves significant gaps for a mutation tool.

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

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

A single front-loaded sentence with the action and resource first and the backup note trailing. Parenthetical '(action=write-text...)' is slightly implementation-leaky but short enough not to waste space.

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

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

There is no output schema, so the description should say what a successful call produces or how conflicts are handled; it does not. With no annotations on a destructive-capable write, the only behavioral detail offered is the backup creation, which is helpful but not sufficient for full confidence.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including the non-obvious 'tenant_id is ignored' note. The description only restates the UTF-8 nature of content/encoding, adding no meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource: write UTF-8 text to a Tealfabric documents path. An agent can distinguish it from nearby read/upload/delete siblings by the 'write text' framing, though it never explicitly contrasts with tealfabric_upload_document, which is the closest alternative for putting content into a document.

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

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

There is no statement of when to use this instead of tealfabric_upload_document or tealfabric_read_document_text, and no prerequisites or conditions are given. Usage is only implied by the verb 'write' and the 'documents path' noun.

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