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

With no annotations, the description carries the full burden, and it does disclose meaningful behavior: the concrete endpoint hit and that a Turnstile/CAPTCHA challenge triggers automatic cookie/browser fallback. It omits what happens on failure, whether credentials are persisted, session lifetime, and what the tool returns or how the resulting session is consumed by sibling tools.

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?

A single front-loaded sentence that leads with the verb and destination, then enumerates the mechanisms. It is dense but every clause carries information; no filler or restatement of the 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?

For a tool with no annotations and no output schema, the definition covers the input side well but leaves the result side blank — whether a session token is stored, returned, or shared with sibling typst_* tools, and failure modes. An agent can invoke it, but cannot predict what it gets back or what to do next.

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 baseline is 3, but the description adds real mapping value by tying the two auth paths to their parameters — POST /v1/auth/signin corresponds to email/password, and the named __Http-typst-session cookie corresponds to sessionCookie, while the 'fallback on challenge' clause explains useBrowserFallback.

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 (authenticate) against a specific resource (typst.app) and names the exact mechanisms: direct email/password API login to POST /v1/auth/signin, or the __Http-typst-session cookie. It is trivially distinguishable from the sibling typst_auth_status, which checks state rather than establishing it.

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 presents two authentication paths (credential login vs. session cookie) and notes a browser fallback, which implies context for choosing an approach. However, it never says when to prefer email/password over a session cookie, whether auth is a prerequisite for the other typst_* tools, or when this should be called rather than typst_auth_status.

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?

With no annotations, the description carries the full burden. It usefully names the three pieces of information returned, but doesn't say whether it performs a network round-trip, what happens when unauthenticated (error vs. empty result), or whether it mutates/refreshes session state.

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?

One tightly scoped sentence with no filler; the most important information (what is checked) comes first.

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 zero-parameter read-only check with no output schema, enumerating the returned facts is largely sufficient. The main omission is the unauthenticated/error behavior an agent would need to interpret the result.

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 zero parameters, so baseline is 4 and there is nothing about which the description could add parameter detail.

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 ('Check') and concrete resources: authentication status, active session cookies, and login method. This naturally distinguishes it from the sibling typst_auth_login, though it doesn't name that sibling explicitly.

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?

There is no guidance on when to call this versus typst_auth_login, or whether it should be run before authenticated operations. Usage is only implied by the word 'Check'.

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?

Since no annotations are provided, the description carries the burden of behavioral transparency. It adds crucial operational details like referencing 'Playwright' for web capture and specifying the output format (PNG previews).

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 dense but highly efficient, dedicating one sentence to defining the entire tool's function and its modes without unnecessary 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?

Given the lack of an output schema, the description is fully self-contained, explaining the nature of the input and the resulting visual verification output.

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 description provides essential context for the function's purpose (visual status verification) which the schema merely implements. It also explains the implication of the 'mode' parameter.

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 goal (capture high-resolution PNG preview screenshots) and precisely defines the two different operational modes ('pages' vs. 'browser'), making it easily distinguishable from standard file read/write tools.

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 distinction between the 'pages' mode (compilation) and the 'browser' mode (live capture) effectively guides the agent on when to use the tool for different visual verification tasks.

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?

With no annotations, the description carries the full behavioral burden. It discloses that files are optional and a compiler version can be pinned, but omits critical context: whether authentication is required (a typst_auth_login sibling exists), what happens on duplicate project names, what the call returns, and whether creation is reversible.

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 a single front-loaded sentence with zero waste; every clause contributes to what the tool creates and what optional inputs it accepts.

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 mutation tool with no annotations and no output schema, the definition is too thin. It should at least mention authentication requirements and expected return behavior; as written, an agent would have to infer these from sibling tools or trial and error.

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 all five parameters are already documented. The description only restates the optional files and pinned compiler version, adding no syntax or behavioral detail beyond the schema, which is the baseline 3 case.

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 — 'Create a new project' — and names the platform, which is enough to distinguish it from list, get, and delete siblings. It does not explicitly contrast with an alternative, but no sibling offers competing creation semantics, so the purpose is clear.

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?

There is no guidance on when to use this tool versus alternatives, no mention of prerequisites such as authentication, and no exclusions or edge-case conditions. Usage is implied by the name alone rather than explained.

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?

No annotations are provided, so the description carries the full burden. It conveys that this is destructive ('Delete') and names the mutation, but says nothing about whether deletion is permanent, what happens when the path does not exist, or whether it cascades to referencing assets.

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?

A single front-loaded sentence with the verb and resource first, then the domain and mechanism. The trailing 'via DeleteFilesMutation' is low-value implementation detail but does not bloat 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 two-parameter, no-output-schema destructive tool, the description covers identity but not consequences, error behavior, or auth requirements. Adequate to identify the call, thin for calling it safely.

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 projectId and filePath are already documented, including the useful detail that filePath accepts a path/name or a file ID. The description adds no parameter information 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: delete a file or asset in a Typst project, and identifies the underlying DeleteFilesMutation. It is distinguishable from typst_delete_project (project-level) and from typst_rename_file/typst_write_file, though it doesn't explicitly say so.

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?

No guidance on when to use this versus typst_rename_file, typst_write_file, or typst_delete_project, and no prerequisites such as auth or membership. The agent must infer usage entirely from the name and schema.

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?

With no annotations present, the description carries the full burden, and it does disclose the single most important trait: the deletion is permanent/irreversible. However, it says nothing about authentication requirements, what happens to files contained in the project, or behavior when the ID does not exist.

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?

One short sentence with the destructive nature front-loaded and zero filler. Nothing in it is redundant or misplaced.

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 destructive tool with no output schema, the definition covers the essential action and irreversibility. It is only slightly thin on prerequisites (auth) and side effects on project contents, which an agent calling a delete tool would want.

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 single projectId parameter is fully documented in the schema, so the baseline is 3. The description's "by ID" merely echoes the schema and adds no format or validation detail beyond it.

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 ("Permanently delete a project") with a scoping hint ("by ID"), which makes it distinguishable from typst_delete_file and typst_get_project without opening the schema. It does not explicitly name or contrast a sibling, so it falls just 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?

There is no guidance on when to use this versus typst_get_project or typst_delete_file, and no stated prerequisites. The word "Permanently" hints at caution but gives no conditional or alternative-routing instruction.

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?

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses atomic save semantics, default exact matching, LF/CRLF resilience, fuzzy fallback behavior, failure-without-saving on malformed or overlapping edits, dryRun preview behavior, and preservation of unchanged characters and BOM.

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 and dense with relevant behavior in only a few sentences. Every sentence contributes either scope, matching semantics, failure behavior, output behavior, or preservation guarantees.

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?

Despite having 11 parameters and no output schema, the description covers the essential edit semantics, failure modes, output modes, and preservation guarantees an agent needs to invoke it correctly. Remaining details are well covered by the fully documented input schema.

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 all 11 parameters, including oldText, expectedHash, matchMode, output, and dryRun. The description adds some useful emphasis on short unique anchors and expectedHash freshness, but most parameter meaning is already present in 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: applying targeted edits to one original file snapshot with a single save. That clearly distinguishes it from full-file writes, but it does not explicitly name or compare against the closest sibling alternatives such as typst_find_and_replace or typst_write_file.

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 useful safety advice to prefer short unique oldText anchors and expectedHash from typst_read_file, but it does not say when to choose this tool over typst_find_and_replace or typst_write_file. Usage is implied by the multi-edit atomic-edit framing rather than stated with explicit alternatives.

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?

With no annotations, the description carries the full burden, and it does disclose a meaningful composite behavior: a file sync side effect plus a compile step plus a save. However, it doesn't say where the synchronized files land, whether local files are overwritten, whether authentication to typst.app is required, or what happens if outputPath is omitted. Those are real gaps for a tool with network and filesystem side effects.

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?

A single sentence of moderate length that front-loads the action sequence (sync, compile, save) with no filler. It reads as a run-on only because it packs three distinct phases into one clause chain.

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-parameter, no-annotation tool with no output schema, the description should state what is returned (a path, a binary, or nothing) and what happens when outputPath is omitted. Neither is covered, though the core three-phase behavior is conveyed.

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 projectId and mainFile are already documented in the schema. The description only reinforces outputPath as the save destination and adds the compile-target framing for mainFile, but does not clarify the optional-vs-required behavior of outputPath. Baseline 3 applies when the schema does the heavy lifting.

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 specific verbs and resources: synchronize project files, compile to PDF, save to outputPath. This is clearly distinguishable from siblings like typst_capture_screenshot or typst_read_file, which do not produce a compiled PDF. It stops short of naming an alternative, so it's clear but not perfectly differentiated.

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?

Usage is implied by the description (you would call this to get a PDF), but there is no explicit statement of when to use this versus e.g. typst_capture_screenshot or typst_read_file, and no prerequisites or caveats are given. The reader must infer the context.

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?

With no annotations, the description carries real weight and delivers: sequential rule ordering where later rules see earlier results, one save per changed file, per-file mutation serialization, and the important caveat that project-wide changes are not atomic across files. Missing are reversibility/undo guarantees and any permission or locking requirements, so it is strong but not exhaustive.

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?

Six compact sentences, front-loaded with the core action and scope, then escalating to batch semantics, output modes, and the atomicity caveat. Slightly dense but no sentence is filler; it could be tightened marginally.

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 12-parameter mutating tool with a oneOf schema and no output schema, the description covers the highest-risk behaviors: save granularity, rule sequencing, dry-run preview, and non-atomicity across files. Given the schema fully documents parameters, the remaining gap is only around return-value shape and rollback, which is minor.

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 all 12 parameters are already documented. The description adds only marginal meaning, mostly restating ordering semantics that the schema's 'replacements' description already states and the output default behavior that the 'output' field already explains. Baseline 3 is appropriate.

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?

Opens with a specific verb+resource ('Find and replace text or regex') and states the two scopes (single file vs project-wide). It is clearly distinguishable from typst_edit_file and typst_grep_project in substance, but never names or contrasts those siblings explicitly, which keeps it 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?

Gives concrete usage context: use the 'replacements' array to batch mappings in one call with one save per file, and preview with dryRun or output='diff'. It does not state when to prefer typst_edit_file for arbitrary rewrites or typst_grep_project for search-only, so no explicit exclusions or 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?

With no annotations, the description carries the full burden and does disclose the key behavioral trait: two execution backends, with local CLI preferred for speed and a zero-binary cloud fallback. It does not mention that web mode may require authentication or what happens when neither backend is available, which keeps it 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?

Two sentences, front-loaded with the resource and the returned data, then the backend nuance. No filler or redundancy; every clause adds 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?

With no output schema, the description compensates by naming the diagnostic fields returned (errors, warnings, line/column, hints) and explaining backend selection. Minor gaps remain around auth requirements for web mode and failure behavior, but an agent has enough to invoke it correctly.

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 parameter documentation is already complete and 3 is the baseline. The description adds only marginal semantic value, echoing the local-vs-cloud tradeoff ('fastest', 'zero-binary fallback') that the mode enum description already explains.

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 ('Retrieve compiler diagnostics ... for a typst.app project') and enumerates the payload (errors, warnings, line/column numbers, hints). It is clearly distinct from siblings such as typst_read_file or typst_export_pdf, which read content or render output rather than report compilation problems.

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?

Usage is only implied: an agent can infer this is the tool to call after editing to verify compilation, and the mode parentheticals hint at when local vs cloud applies. There is no explicit statement of when to prefer this over alternatives (e.g., read_file for inspecting source) or any prerequisites, so the guidance stays at the minimum-viable level.

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?

No annotations are provided, so the description carries the full burden. It discloses what is returned (metadata, permissions, compiler version, file tree), which is useful behavioral context. However, it does not explicitly state that the operation is read-only, whether authentication is required, or any rate limits—details an agent might need for a project access tool.

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 a single, front-loaded sentence that efficiently lists the key returned information. Every phrase earns its place, and there is no redundant or vague language.

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 read tool with one parameter, no output schema, and no annotations, the description provides a clear inventory of what the agent will receive. It is nearly complete, though it could mention authentication or read-only behavior to fully cover the lack of annotations.

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 has 100% description coverage for the single parameter, so the baseline is 3. The description adds no additional meaning about the 'projectId' parameter beyond what the schema already provides, which is acceptable given the high 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 uses a specific verb ('Get') and enumerates the resource contents: detailed metadata, access permissions, pinned compiler version, and full file tree. It clearly distinguishes this tool from list_projects and list_files by scoping to a single project's full details. However, it does not explicitly name sibling tools to differentiate further, keeping it at a 4.

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 usage is implied: an agent would infer this is for inspecting a project's details. There is no explicit statement of when to use this versus list_projects or list_files, nor any exclusions or prerequisites. The context is clear enough to be minimally viable but lacks direct guidance.

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?

With no annotations, the description carries the burden and does disclose useful behavior: regex or literal matching, and that results include file paths, line numbers and optional context. It omits the read-only/non-mutating guarantee, the default match limit, and any scope or performance caveats.

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 tightly written sentences with the operation front-loaded and the return format second. No filler, though it could fold in one routing hint without bloat.

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 an eight-parameter read tool with a fully described schema and no output schema, the description covers what it does and what comes back. The missing piece is the behavioral context that annotations would normally supply, such as read-only safety and the default result limit.

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 every parameter including glob, path, limit, context, literal and ignoreCase is already documented in the schema. The description adds only that regexes are supported by default, which the schema also implies; 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 for text or regex across files in a Typst project, and summarizes the return shape. It is clearly distinguishable from typst_find_and_replace and typst_read_file by being read-only search, though it never names a sibling explicitly.

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?

Usage is only implied by the verb 'search'. There is no guidance on when to prefer this over typst_read_file or typst_list_files, nor on when a regex versus literal search is appropriate beyond the parameter default.

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?

With no annotations, the description carries the full burden, and it does add real value by disclosing what the listing contains (Yjs text files plus binary asset blobs) even though no output schema exists. However it says nothing about pagination, ordering, whether directories are included, or authentication 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?

A single front-loaded sentence with no filler. The scope ('inside a project') and the content description both land before the sentence ends.

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 no output schema, the description covers purpose and return content adequately. Minor gaps remain around authentication and result shape, but nothing essential to invoking 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?

Only one parameter, and the schema already documents projectId at 100% coverage ('The Typst project ID'). The description reinforces the project scoping but adds no format, sourcing, or validation 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?

States a specific verb and resource ('List all files ... inside a project') and even enumerates the resource subtypes ('multiplayer Yjs text files and binary asset blobs'). It is clearly distinguishable from typst_list_projects and typst_read_file, though it does not explicitly name those siblings as contrasts.

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 never says when to call this instead of typst_list_projects or typst_get_project, nor does it mention prerequisites such as needing a projectId obtained elsewhere. Usage must be inferred entirely from the object ('inside a project').

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?

With no annotations, the description carries the full burden, and it does disclose the auth precondition ('authenticated user') and that both owned and shared/external projects are included — a meaningful behavioral fact. It does not disclose whether results are paginated, ordered, or truncated for large accounts.

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?

One sentence, verb and scope front-loaded, zero filler. Nothing in it is redundant with structured fields.

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 parameterless read tool with no output schema, the description covers source and scope; the only gap is that it does not indicate what a returned project entry contains or whether results are grouped by owner vs shared. That is a minor omission for such a simple 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond scope; the baseline for a parameterless tool applies. The 'owned and shared/external' qualifier usefully narrows what the empty call returns.

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 (List) and resource (projects), plus the scope 'owned and shared/external', which separates it from typst_get_project (single project) and typst_list_files (files inside a project). It does not explicitly name those siblings, but the resource noun makes the distinction readable.

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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative; usage is only implied by the scope (enumerate dashboard projects, likely to obtain project identifiers for typst_get_project / typst_list_files). Adequate but leaves routing 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?

With no annotations, the description carries the burden and does disclose real behavior: default 200-line/16 KiB paging, continuation via offset, image files returned as native image blocks, and that contentHash covers the whole raw file. It doesn't say what happens on missing files or non-text assets, which keeps it 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?

Four dense sentences, front-loaded with the core capability, then pagination, hash, and output-mode details. Slightly terse in places but no filler 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?

Covers what content contains, what contentHash is for, what compact/full change, and how pagination behaves, which is enough to call a read tool with no annotations and no output schema. Error handling and image-specific paging limits are the only notable omissions.

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; the description adds useful meaning about pagination continuation and the compact-vs-full metadata distinction. However, it refers to 'nextOffset' when the actual parameter is 'offset', which can mislead an agent about the parameter name.

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 ('Read project text ... or images as native image blocks') plus scope ('in bounded pages'), and explicitly routes large-file lookups to grep, so it is distinguishable from typst_grep_project and the write siblings.

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 concrete guidance: use grep to locate lines before reading large files, use nextOffset to continue, and pass contentHash as expectedHash to typst_edit_file. It lacks an explicit 'when not to use' or a note on how it differs from typst_list_files, but the intended workflow is clear.

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?

With no annotations, the description carries the full burden and only adds an internal implementation detail (UpdatesFileMutation). It does not disclose whether an existing destination file is overwritten, whether new directories are created, permission/auth requirements, or what the mutation returns — material gaps for a mutation tool.

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?

A single front-loaded sentence with no filler. The trailing 'via UpdatesFileMutation' is the only element of dubious value to an agent.

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?

A three-required-parameter mutation with no annotations and no output schema needs more: overwrite behavior, error conditions on missing source or colliding destination, and expected result are all unaddressed. The description is too thin for the tool's complexity.

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 all three parameters (projectId, filePath, newName) are already documented in the schema. The description adds no format or path semantics beyond that baseline, which is acceptable given 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 pair (rename or move) and resource (a file) scoped to a Typst project, which is clear enough for an agent to distinguish it from read/write/delete file siblings. It stops short of naming or contrasting those siblings explicitly.

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 rename/move framing implies when the tool applies versus typst_write_file or typst_edit_file, but no explicit when-to-use, prerequisites, or alternative routing is given. Usage must be inferred.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that the tool can overwrite an existing asset ('replace') and accepts either a local path or base64 payload, but it omits authentication requirements, overwrite/destructive semantics, size limits, and how conversion interacts with the upload.

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?

A single, front-loaded sentence that names the action, resource, formats, destination, and source options without filler. Every clause contributes useful 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 5-parameter upload tool with no output schema, the description covers purpose, asset types, destination, and source methods adequately, and the rich input schema fills in parameter details. The main gap is the lack of any auth or overwrite-safety context, which matters because annotations are absent.

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 all five parameters in detail. The description reinforces that source data can come from a local path or base64, but it adds no meaningful semantics beyond the schema, especially for the undocumented-in-description 'convert' parameter.

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 uses a specific verb pair ('Upload or replace') and a precise resource ('binary asset') with concrete examples (PNG, JPG, SVG, PDF, font). It distinguishes itself from text-file siblings such as typst_write_file by explicitly framing the tool around binary assets and local file/base64 sourcing.

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 binary-asset framing implies when this tool applies, and the source options (local path vs base64) are clear. However, it does not explicitly say when to use this over siblings like typst_write_file or typst_edit_file, nor does it state exclusions or prerequisites.

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?

No annotations are provided, so the description carries the behavioral burden. It usefully discloses Yjs CRDT synchronization via WebSocket and REST endpoints and notes that it creates or overwrites, but it omits authentication requirements, overwrite consequences, error behavior, and limits.

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?

It is a single front-loaded sentence with the main action stated first. The WebSocket/REST detail is dense but still relevant, and there is little wasted text.

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 mutation tool with no annotations and no output schema, the description is adequate but incomplete: it does not mention authentication prerequisites, failure modes, return behavior, or how it relates to typst_edit_file. The fully described input schema compensates partially.

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 all four parameters are already documented in the input schema. The description adds only file-type examples and no additional parameter semantics, so the baseline of 3 is appropriate.

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: "Create or overwrite a text file" in a typst.app project. It is clear what the tool does, though it does not explicitly distinguish itself from the sibling typst_edit_file 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 implies use for creating or overwriting files but gives no explicit guidance on when to use this versus typst_edit_file or other file tools. There are no when-not conditions or alternative recommendations.

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