LetX

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the description's real value is explaining the *mechanics* of that destruction: the source is saved to the user's "AI Scratchpad" project, files of the same name are replaced, and earlier versions survive in project history. It also discloses return behavior (PDF download link plus LaTeX errors on failure) and the text-only input constraint. It stops short of naming auth/permission requirements or size/time limits, so 4 rather than 5.

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?

Front-loaded with the purpose and the project-free scoping in the first clause, then side effects and return values. Four sentences all carry information; only the compiler-default remark is arguably redundant with the schema. No filler or restatement of the tool name.

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 exists, yet the description supplies return semantics (PDF download link, LaTeX errors when compilation fails). For a 3-parameter tool with a persistence side effect, the description covers input constraints, side effects, history behavior, and outputs — nothing an agent needs to call it correctly is missing.

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%, so the schema already documents main_tex, files[].path/content, and the pdflatex/xelatex/lualatex options. The description adds only a mild constraint (text files only, no images) on the files parameter and nothing on format or syntax the schema doesn't already carry. Baseline 3 is correct.

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+resource (compile LaTeX source to PDF) and immediately scopes it against the sibling project-based path: "without choosing a project: the main .tex content plus optional extra .tex, .bib or .sty files." An agent can distinguish it from compile_project without opening either schema.

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 names the triggering condition ("Use when the user wants a PDF of LaTeX that is in the conversation") and the implicit alternative is disambiguated by "without choosing a project" and "Text files only, no images." Both when-to-use and when-not are inferable with no guessing.

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

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

Annotations declare readOnlyHint=false and idempotentHint=false, and the description adds real value on top: it discloses that compilation returns a PDF link and, on failure, surfaces LaTeX errors from the log rather than a bare error. It does not say where the PDF is stored, whether results are cached, or what permissions are needed, so it falls short of a 5.

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, front-loaded with the action, then usage, then return behavior. No filler and nothing important buried.

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?

With no output schema, the description correctly compensates by explaining the return value (PDF link plus LaTeX errors) and the usage trigger. The remaining gap is the missing differentiation from compile_latex and the absence of any note on permissions or artifact location.

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?

There is only one parameter and schema description coverage is 100%, so the schema already fully documents project_id. The description adds no format, scoping, or sourcing detail beyond it, which is the expected baseline when the schema does the work.

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 ("Compile one of the user's letX projects"), so the action is unambiguous. However, it never distinguishes itself from the very close sibling compile_latex, leaving the agent to guess which compile tool applies to a project versus raw LaTeX.

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?

Gives two concrete triggering situations: the user wants a PDF, or wants to verify the project builds. That is clear context for when to use it, but there are no exclusions or explicit routing to the sibling compile_latex.

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

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write, so the safety bar is largely covered. The description adds useful behavior beyond that: main.tex is required, and the call yields a project id and an editor link. It omits auth/permission requirements and what happens on duplicate names, keeping it below 5.

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 tight sentences: purpose and required input first, then the usage condition, then the return value. No filler or redundancy; every sentence carries load.

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?

With no output schema, the description compensates by naming the return values (project id, editor link), and it covers the required-file constraint and when to use it. Missing pieces are minor: no error/duplicate behavior and no explicit pointer to the template-creation sibling.

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 100% and all three parameters (name, files, compiler) are documented in the schema itself, including the compiler enum values and the main.tex expectation. The description adds nothing beyond that baseline, so a 3 is correct.

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 gives a specific verb and resource ('Create a new letX project') plus the input source ('from LaTeX files'), and flags a required artifact (main.tex). It implicitly differentiates from create_project_from_template by specifying files rather than a template, but never names a sibling explicitly, so it stops short of 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?

It states a clear when-to-use condition: 'Use when the user wants their document saved as a letX project they can open, share and keep editing.' No exclusions or named alternatives are given (e.g. when to prefer create_project_from_template or create_project_from_template vs compile_project), so it misses the 5 criteria.

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

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

Annotations already declare non-readonly, non-idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds real value by disclosing the scoping ('for the connected user') and the return payload (project id plus editor link), which is important since there is no output schema.

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, zero filler, front-loaded with the action and the when-to-use condition before the return description. Every sentence earns its place.

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?

For a single-parameter creation tool with no output schema, the description covers the action, the trigger, and the return shape, which is what an agent needs. Minor gap: no pointer to the sibling that lists/searches templates for obtaining the slug.

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?

Only one parameter and schema description coverage is 100%, so the schema already defines 'slug'. The description restates it as 'a template slug' without adding format, discovery, or validation detail (e.g., where to obtain the slug), so it stays at the baseline.

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 (create), resource (letX project), actor (connected user), and source (template slug). The 'from a template slug' qualifier distinguishes it from the sibling create_project, which presumably creates a blank project.

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?

'Use when the user wants to start a document from a template' gives a clear triggering condition. It stops short of naming the alternatives (create_project for blank projects, search_templates/get_template for discovering slugs) or stating when not to use it.

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

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

The description aligns with the annotations: fetching by id is a read-only operation and not destructive. It adds that the call returns the full record and is a minimal fetch interface, but it does not add much behavioral context beyond what the annotations already establish.

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 compact sentences, front-loads the core action and resource, and includes no wasted text. The secondary sentence adds useful usage context without bloating the definition.

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?

For a simple one-parameter read tool with rich annotations and no output schema, the description is largely complete: it names the resource, lookup key, and return scope. The main omission is any explicit relationship to the sibling get_template tool.

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%, and the only parameter, id, is already documented in the schema as the template record's id. The description repeats this without adding format or constraint details beyond the schema.

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 gives a specific verb and resource: fetch one letX LaTeX template record by its id. It is clear enough to distinguish search-style tools from a direct id lookup, but it does not explicitly distinguish itself from the sibling get_template tool.

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?

It states a clear usage context: use it when the full record of a template found by search is needed. It also frames itself as a minimal interface for clients that expect one, though it gives no explicit when-not guidance or alternative such as get_template.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds value by enumerating what comes back (description, author, license, preview image, letx.app page) even though no output schema exists, though it is silent on behavior when the slug doesn't resolve.

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?

Two tight sentences: the retrieval and returned fields come first, usage guidance second. Nothing is redundant and nothing could be cut without losing information.

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?

For a single-parameter read with no output schema, the description compensates by listing the returned fields, which is the main completeness risk here. The remaining gap is error/not-found behavior, which is minor for a lookup tool.

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?

Only one parameter and schema coverage is 100%, so the schema already explains 'slug'. The description reinforces that lookup is 'by its slug' but adds no format, casing, or slug-derivation guidance beyond the schema, so baseline 3 applies.

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 ('Get one LaTeX template's full details') and pins the lookup key to a slug, which clearly separates it from the multi-result sibling search_templates. An agent can tell what it retrieves without opening the schema.

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?

'Use when the user wants to know more about a specific template' gives a clear positive trigger, implicitly contrasting with discovery via search_templates. It stops short of explicitly naming that alternative or stating when not to use it (e.g. when the slug is unknown).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful scope (one project, both document and asset types) and promises 'exact paths' in the result, but says nothing about ordering, pagination, or whether results can be large — minor gaps for a read-only listing.

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?

Two sentences with no filler: the resource inventory and scope come first, the usage trigger second. Nothing is redundant with the title or schema.

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?

For a single-parameter read-only listing with no output schema, the description covers scope, content types, and the key return element (exact paths). It would be fully complete if it noted result volume or ordering, but an agent can call it correctly as written.

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?

There is a single parameter at 100% schema description coverage, so the schema already documents project_id. The phrase 'one of the user's letX projects' implies the id scopes to a project the user owns, adding slight meaning, but offers no format hints (UUID vs slug) beyond the schema.

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 gives a specific verb (list) and a precisely scoped resource: documents AND uploaded assets (images, data files) within a single letX project. That content scope cleanly separates it from list_projects (projects, not files) and read_project_file (one file's content). It stops short of naming a sibling explicitly, so it sits just below the top band.

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?

'Use when the user asks what a project contains or a file path is needed' gives two concrete triggering conditions. No exclusion clause is offered (e.g., 'to read a file's contents, use read_project_file instead'), so an agent must infer the boundary from the sibling names.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds the scope constraint ('connected user's') and the return fields, which is real value, but says nothing about ordering, empty-list behavior, or auth requirements.

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?

Two sentences, zero waste, with the capability first and the invocation cue second. Nothing is repeated from the title or annotations.

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?

With no parameters, no output schema and full annotation coverage, the main open question was what the call returns, and the description answers it by naming the fields. Ordering, pagination and empty-result handling remain unstated, which keeps it short of 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?

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The mention of returned fields (name, id, last update) is a small bonus but concerns output, not inputs.

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?

Specific verb + resource ('List the connected user's letX projects') plus the returned fields (name, id, last update), so an agent knows exactly what it gets back. No sibling lists projects, so there's no ambiguity to resolve.

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 states the trigger condition: use when the user refers to their projects or when a project id is needed. That second clause usefully routes the agent here as a prerequisite step for tools like list_project_files or compile_project. It stops short of naming alternatives or exclusions, but for a zero-param listing tool there are none to name.

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

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

Annotations already declare this is read-only, non-destructive, and closed-world, so the safety profile is covered. The description adds project scope and path examples, but does not describe return content, errors, or whether reads are always idempotent.

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 short and front-loads the core action and examples. The docs link is compact and the sentences are efficient, though the 'wants it changed' phrase adds ambiguity rather than value.

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?

For a simple two-parameter read tool with full schema coverage and clear read-only annotations, the description is largely sufficient. It could more clearly distinguish reading from updating, but no critical invocation detail is missing.

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 100%, so both required parameters are already documented. The description repeats path examples but adds no syntax, constraints, or meaning beyond the schema.

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 a specific verb and resource: read a document from a letX project. It gives concrete file examples and scopes the tool to project files, which distinguishes it from listing projects or compiling projects.

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?

It gives a clear usage context for reading files, but the phrase 'or wants it changed' is ambiguous and does not explicitly point to update_project_file. No when-not conditions or explicit sibling alternatives are provided.

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

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

Annotations already cover the safety profile (readOnly, non-destructive), so the valuable addition is the disclosure that results carry id, title and URL — especially useful since there is no output schema. It omits result limits and pagination behavior, which an agent needs to know before calling.

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, front-loaded with the resource and return shape, with no filler. The clause about being a minimal interface is slightly meta but does earn its place by hinting at the sibling relationship.

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?

For a single-parameter read-only tool with full schema coverage and annotations, the definition covers what it searches, what it returns, and roughly when to use it. The remaining gap is disambiguation from the near-identical `search_templates` sibling.

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?

One parameter at 100% schema coverage, so the schema already documents `query` as 'search terms'. The description adds nothing about query syntax, matching behavior, or empty-result handling, so the baseline 3 applies.

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 ('Search letX's public library of free LaTeX templates') and names the returned fields (id, title, URL). It does not explicitly distinguish itself from the sibling `search_templates`, only hinting at a difference via 'minimal search interface for clients that expect one'.

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?

'Use when the user is looking for a LaTeX template' gives a use context, and 'for clients that expect one' implies this is the fallback shape. But it never names `search_templates` as the richer alternative or states when NOT to use this tool, leaving the most important routing decision to inference.

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

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

Annotations already declare read-only, non-destructive, closed-world behavior. The description adds useful behavioral context: the library size, that templates are free, and what is returned (slug, category, preview link). It does not disclose result limits, ranking, or pagination behavior, which keeps it from a 5.

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 front-loaded with the verb and resource, followed by a clear usage sentence and return-value sentence. The long category parenthetical is informative and earns its place, though it is slightly verbose.

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?

For a simple two-parameter search tool with rich schema coverage and annotations, the description covers purpose, usage, scope, and return fields. The main missing context is pagination or result-limit behavior, which matters somewhat for a 1000+ template search.

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 100%, so both the required query parameter and optional category parameter are already fully documented. The description's parenthetical category examples add some useful context but do not meaningfully extend parameter semantics beyond the schema.

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 gives a specific verb ('Search') and resource ('LaTeX templates') plus scope details such as the 1000+ free template library and template categories. It clearly identifies this as a discovery/search tool, but it does not explicitly distinguish it from the close sibling get_template for retrieving a known template by slug.

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?

It explicitly states when to use the tool: when the user wants a LaTeX template or a starting point for a document. It does not state when not to use it or name alternatives like get_template, so the guidance is clear but not complete.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description usefully adds that the default engine is set at project creation, but it never says whether changing the engine recompiles or invalidates existing outputs, or whether the change applies only to future builds — a real gap for a project-level mutation.

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 sentences, purpose front-loaded, then value-selection rules, then usage trigger. No filler; each sentence carries information the agent needs to act correctly.

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?

For a two-required-param, no-output-schema tool with full schema coverage, the description covers purpose, value choice and trigger. Only the post-change effect (recompilation/regeneration of output) is unstated, which is a minor but real omission.

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%, so the baseline is 3, and the description goes beyond it by giving decision criteria for the enum-less 'compiler' string (which LaTeX packages/document features require which engine). project_id is left to the schema, which is fine since it is self-describing.

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+resource ('Set the TeX engine a project builds with') and immediately enumerates the three legal values. It also implicitly separates itself from create_project by noting 'letX picks an engine when a project is created', so an agent can distinguish it from the sibling that creates projects.

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?

Gives an explicit trigger ('Use when the user asks for a different engine or the document needs one') plus per-document routing rules: fontspec/unicode-math/polyglossia/xeCJK need xelatex or lualatex, and \directlua/luacode needs lualatex. That is more than context — it tells the agent which value to select and why.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true; the description adds meaningful context beyond them by explaining the replace-vs-create branch and that the previous version is preserved in letX history and can be undone. That softens an otherwise destructive operation. It omits permission/auth requirements and failure modes, so not a 5.

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?

Two tight sentences front-load the create/replace semantics, then the history/undo consequence, then the usage trigger. No sentence is redundant and the docs link is a brief appendix.

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?

For a 3-required-param write tool with no output schema and annotations covering the safety profile, the description covers create/replace behavior, reversibility, and when to invoke it. It does not address error cases (missing project, path conflicts) or what the call returns, leaving a small gap.

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 100%, so the schema already documents path, content, and project_id, including the 'FULL new content' replacement warning and the create-if-absent behavior at the path level. The description reinforces but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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 pair and resource: 'Create or replace a document in one of the user's letX projects.' An agent can immediately separate it from read_project_file, list_project_files, and create_project without consulting any schema.

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?

Gives a clear trigger condition: 'Use when the user asks to change or add a file in a project,' which pins it to file writes rather than project creation. It does not explicitly name the alternative (read_project_file) or state when NOT to use it, so it falls short of full routing guidance.

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