careers_download

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

Annotations already mark the operation as non-read-only, non-idempotent, non-destructive, and open-world. The description goes beyond this by revealing that it generates a filename, is cookie-free and allowlisted, enforces a 100 MiB/40-second budget, and rejects arbitrary paths/uploads/external fetches. This materially informs the agent about side effects and constraints that annotations do not capture; no contradiction.

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

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

Three short sentences, with the primary action and destination front-loaded and constraints stated compactly. Each clause adds distinct information—privacy, filename generation, transport mode, budget, and exclusions—so there is no redundancy or filler.

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

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

The definition covers the tool's restrictions, budget, and security model, and the output schema exists for return-value details. The main gaps are minor: it doesn't state authentication prerequisites or how 'permitted' is determined, though sibling auth tools make that inferable. Overall it gives an agent enough to invoke correctly for a simple two-parameter download.

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 provides 0% description coverage for kind and item_id, and the description does not explain either parameter. It only loosely implies that item_id references a 'permitted existing file,' and the kind enum values are self-descriptive but the description never maps them. With weak schema coverage and no compensatory detail, parameter understanding is largely left to inference.

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 action ('download'), a resource ('permitted existing file'), and a destination ('generated filename on the MCP host'), so the agent knows what the tool accomplishes. It avoids tautology and conveys a distinct download-with-restrictions operation. However, it does not explicitly differentiate from sibling blackboard_download, so it stops short of full sibling-level clarity.

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

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

The description provides clear context: it is a 'cookie-free allowlisted file transport' with a '100 MiB/40-second budget' and explicitly lists exclusions ('No arbitrary paths, uploads or external URL fetches'). This implies the intended use case—downloading permitted file objects—but does not name any alternative tools or when-not conditions, so it is not fully explicit.

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