compile_project

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

Annotations only declare it is not read-only and is open-world; the description adds the crucial behavioral facts: the call is asynchronous (returns a job ID immediately), has a remote-first fallback on timeout/service errors, and requires latexmk plus the selected engine locally. It does not disclose failure surface (compile errors surfacing only via polling) or whether a prior PDF is overwritten.

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?

Four short sentences, front-loaded with the async contract before the mode details and the polling instruction. Slightly dense phrasing ("for this build PDF and logs") but no wasted sentences.

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?

No output schema, five parameters, and zero schema descriptions put the burden on the text, which covers the async model and dependencies but omits what the job ID is used for downstream, what rootPath/timeout do, and how build failure is reported. Adequate to invoke, not fully complete.

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 0%, so the description must carry parameter meaning, and it only explains mode (auto = Overleaf first, local fallback) and lightly touches compiler ("the selected engine"). rootPath, timeoutSeconds, and projectId are entirely undocumented, leaving three of five parameters undefined in both schema and 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?

States a specific verb and resource ("Start compilation") plus the return contract ("return a job ID immediately"), which distinguishes it from siblings like get_compile_result. An agent can tell this is the kick-off of an async build, not a status check.

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?

Explicitly routes the agent to "Poll get_compile_result for this build PDF and logs", which names the follow-up step and the sibling. It also explains when the auto fallback kicks in (timeout/service errors). Missing only an explicit statement of when not to use it (e.g., prefer get_compile_result when a build is already running).

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