ghl_form_upload_custom_files

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

The description explicitly discloses a critical behavioral trait: the tool currently cannot accept file bytes due to a missing request body schema. This goes beyond annotations, which only indicate readOnlyHint=false and openWorldHint=true. The limitation is honestly stated, giving the agent a clear understanding of the tool's current capability.

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 poorly structured, starting with a lengthy technical note about a registry limitation that dominates the space. The actual upload instructions are brief but buried. While the technical note may be contextually important, it harms conciseness and discoverability. The description could be trimmed to focus on usage.

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

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

Given the tool's complexity (multipart upload, custom fields, no output schema), the description omits important context: what the API returns on success/failure, how to handle errors, and whether the tool works at all (contradictory exception note). The coverage is incomplete for an agent to use this tool effectively, especially missing response format.

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

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

The input schema has 100% coverage with descriptions for all three parameters. The description adds significant value by explaining the required key format for file fields ('<custom_field_id>_<file_id>'), allowed MIME types, size limit, and support for multiple files. While the body parameter's description in the schema already hints at multipart uploads, the description provides concrete, actionable details.

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 'Upload files to custom fields' and explains the key format, which clarifies the intended operation. However, the prominent technical note declaring the tool non-functional ('no way to attach file bytes') directly contradicts the purpose and may confuse an agent evaluating whether to use it. The purpose is clear in principle but undermined by the exception note.

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 formatting details (key format, allowed types, size) but offers no guidance on when to use this tool versus alternatives. No comparison with sibling tools like ghl_location_upload_file_custom_fields is made. The agent is left to infer usage context 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.