tokportal_upload_video_direct

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

Annotations show readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the agent knows this is a non-read, non-destructive, non-idempotent operation. The description adds that it uses multipart/form-data and returns a public video URL. However, it doesn't disclose important behavioral traits: file size limits, accepted video formats, authentication requirements beyond typical TokPortal auth, or whether existing uploads get overwritten. The description adds modest value beyond annotations but is not comprehensive.

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

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

The description is two sentences long and front-loaded with the key action. The first sentence states the purpose, the second elaborates on method and outcome. Every word earns its place. It could be slightly improved by clarifying that 'direct' means local file upload, but it's already quite efficient.

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

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

Given there is no output schema, the description correctly mentions the return type (public video URL). However, it doesn't explain what bundle_id means or how to obtain it (likely from a prior tokportal_create_bundle or similar). Among 70+ sibling tools, there are several related to bundles and uploads, so more context on prerequisites (e.g., 'Bundle must exist and not be finalized') would help. The complexity is moderate, and the description is adequate but not thorough.

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%, meaning all 3 parameters have descriptions in the schema. The description mentions 'uploads multipart/form-data' which aligns with the idempotency_key parameter (used as a header) and file_path (local file). The bundle_id is described as 'Multipart form field bundle_id' in the schema. The description adds the context that these are multipart fields and that the return is a public URL, but doesn't explain the semantics of bundle_id (likely links the video to a bundle) beyond what the schema says. Baseline 3 is appropriate given full schema 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?

The description states the tool uploads a video file directly via multipart/form-data through TokPortal and returns the public video URL. This clearly identifies the verb (upload), resource (video file), method (direct multipart/form-data), and outcome (returns public URL). It distinguishes from tokportal_upload_video (which likely handles uploads differently, possibly via URL or indirect method) and from other upload tools like tokportal_upload_image_direct. However, it doesn't explicitly name the sibling it differs from, so not a 5.

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

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

The description implicitly suggests this is for direct video file uploads. However, it provides no explicit guidance on when to use this vs alternatives like tokportal_upload_video, tokportal_upload_image_direct, or tokportal_upload_image_from_url. It also doesn't mention prerequisites (e.g., must have a local file, need bundle_id from prior create_bundle call) or when not to use it (e.g., for images or remote URLs). The context is implied but not explicit.

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