ghl_social_csv_upload

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

The description excels here: it explicitly states that the tool requires a pre-encoded multipart/form-data payload, that `body` is sent verbatim, and that the `file` parameter is binary CSV. These critical behavioral details go far beyond annotations (which only mark readOnlyHint=false and destructiveHint=false) and help avoid common mistakes.

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 moderately concise but includes verbose endpoint details (path, version, source) that could be condensed. The critical behavioral note about pre-encoding is front-loaded, but there is some redundancy (e.g., 'Upload CSV' repeated). It could be tighter.

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 with special payload requirements), the description covers essential behavioral aspects like payload construction, required parameters, and OAuth scopes. It does not mention success/error responses, but there is no output schema to describe them. Overall it provides adequate context for correct usage.

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 100% schema coverage, the schema already documents both parameters. However, the description adds crucial context: `body` is sent verbatim to GHL, and the caller must provide a pre-encoded multipart payload. This clarifies the parameter's real usage beyond the schema's 'Request body' description.

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

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

The description clearly states the tool uploads a CSV file for bulk social media posting, which is a specific verb-resource pair. It also distinguishes from media upload by noting there is no URL-based alternative. However, it doesn't explicitly differentiate among sibling social tools beyond this one 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 no explicit guidance on when to use this tool vs alternatives. It mentions there is no URL-based alternative unlike media upload, but does not specify scenarios or prerequisites like having a pre-encoded payload. Sibling tools are abundant but no selection criteria are given.

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