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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description does not need to state that this writes. It adds genuine behavioral context that annotations cannot: the comment remains attached to the anchored text even after the file changes. It omits what a repeated call will do given idempotentHint=false (likely a duplicate comment) and what happens if anchor_text is not found.

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 padding, and the anchoring modes are front-loaded before the persistence note. Every clause carries information an agent would not get from the schema 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?

For a 7-parameter mutation tool with no output schema, the description covers the one genuinely ambiguous decision (targeting strategy) and one non-obvious behavior (anchor persistence). It leaves out error behavior when anchor_text or the line range is invalid, and it does not mention what is returned, which is a modest gap given the absence of an output 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 coverage is 71% and the schema already documents path, content, project_id, and occurrence. The description adds real meaning by presenting the anchor_text/occurrence combination as an alternative to a line range, which the schema does not express. However, it does not clarify whether start_line and end_line must be supplied together or whether end_line is optional, leaving the least-documented parameters ambiguous.

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 plus resource ('Add a review comment to a text file') and it names the two anchoring modes. Reading the description alone, an agent can distinguish this from typst_reply_comment, typst_list_comments, and typst_resolve_comment without opening 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?

The description states the two creation modes (exact-text anchor with occurrence disambiguation, or line range), so an agent knows how to select an anchor. It does not explicitly route against siblings such as typst_reply_comment ('reply to an existing thread') or say when line-range anchoring is preferable to text anchoring.

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 idempotency, non-destructiveness, and open-world behavior. The description adds useful behavioral context: compile errors and warnings include file and line information, the output path is returned, preview images are returned inline, and @preview packages are downloaded automatically. It does not detail failure modes or blocking behavior, but the added context is meaningful.

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 focused sentences, front-loaded with the core action and return shape, followed by the usage cue and the preview behavior. Every sentence adds information without repetition.

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 does a good job explaining what the tool returns: errors/warnings with location, an output path, and optional inline images. It also covers automatic package downloading. A fully complete description might mention how fatal compile failures are reported, but the essentials are present.

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 83%, so the baseline is 3. The description adds value by explaining the key interaction that 'png' plus preview_pages>0 returns inline page images, which is not obvious from the schema alone, though it does not add detail for ppi, main_file, or output_path beyond what the schema provides.

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 ('Compile a project with the local typst CLI') and clearly distinguishes this tool from all sibling tools, none of which perform compilation. It also specifies the primary outputs: errors/warnings with file and line, the output path, and optional inline page images.

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 explicit guidance to use the tool after edits to check that the document builds, and it explains that format 'png' with preview_pages>0 is the way to inspect layout visually. No alternative tools are named, but there is no sibling compiler to route to, so the context is sufficient.

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 the write, non-idempotent, open-world nature. The description adds useful context: it returns the new project ID and can create from a template, but it doesn't mention permissions or error behavior beyond that.

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 core action and immediately followed by how to supply optional parameters. No wasted words.

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 four parameters, one required, and no output schema, the description provides enough: it clarifies return value (project ID) and how to obtain template and team_id. It doesn't cover failure modes, but annotations cover safety.

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 75%, with team_id, template, and template_version documented. The description adds meaning by linking team_id to typst_whoami and template to typst_search_templates, though the required 'name' parameter is left to 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: 'Create a new project'. It distinguishes the tool from siblings like duplicate_project and update_project by specifying creation and noting the empty-or-template option.

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 guides the agent to use typst_search_templates to find a template and typst_whoami to get team_id. It doesn't state when to avoid this tool in favor of alternatives like duplicate_project, but the context 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?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is carried by structured data. The description adds the key extra fact that deletion is permanent (as opposed to the reversible resolve), which tells the agent this is not a soft-state change. It omits replay/second-call behavior and whether replies in the thread go with it, keeping 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 short sentences, front-loaded with the destructive action and followed by the routing rule. No filler, nothing to trim.

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 delete with full annotation coverage and no output schema, the description gives the agent enough to act safely and pick the right sibling. The remaining gap is the undocumented comment_id expectation (e.g., from typst_list_comments) and whether threaded replies are removed.

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 says nothing about either parameter. Schema coverage is only 50%: project_id carries a description and a concrete example format, but comment_id is a bare string in both schema and prose. With two required params and a coverage gap, the description should have compensated and does not.

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 comment thread') and immediately contrasts it with the sibling typst_resolve_comment, so the agent can distinguish the destructive path from the soft path 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?

Explicitly names the preferred alternative and the condition that selects this tool instead ('unless the user asks to delete'). That is a complete when/how routing rule in one clause.

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=false, but 'Permanently' adds the non-obvious fact that deletion is irreversible with no trash or undo path. The confirmation instruction is extra behavioral context beyond the annotations. Missing details on partial failure or batch semantics keep 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?

Two tight sentences with the destructive scope front-loaded and the safety instruction second. No filler or redundant restatement of the 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?

A destructive batch mutation with no output schema needs more than this: it omits what happens on nonexistent paths, whether deletion is atomic across the paths array, and what is returned. Annotations carry the safety profile, which keeps it at minimum-viable rather than inadequate.

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 only 50%, and the description adds nothing about the parameters — it does not clarify that 'paths' accepts both project-relative paths and file IDs, or how multiple paths are handled. The description is silent where the schema is thin.

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 files from a project'), which is clearly distinct from typst_delete_project at the noun level. It does not explicitly contrast with the project-level deletion sibling, so the agent must infer the scope difference.

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?

Adds a real precondition ('Confirm with the user before deleting anything they did not explicitly ask to remove'), which is useful guidance for a destructive tool. However, it gives no routing advice among siblings such as typst_delete_project or when to prefer typst_edit_file over deletion.

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?

While annotations provide the 'destructiveHint', the description adds critical behavioral context regarding the required safety behavior of the function, specifically that 'confirm_name must equal the project's exact name as a safety check.'

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 definition is brief, uses two highly informative sentences, and front-loads the core action, ensuring no unnecessary words are used.

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 highly sensitive and destructive operation, the description is perfectly complete. It covers permanence, required checks, and intent constraints, leaving no ambiguity for the agent.

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?

Even with 100% schema coverage, the description adds significant semantic weight to the 'confirm_name' parameter by explaining that it is a required safety check using the project's exact current 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?

The purpose is extremely clear: 'Permanently delete a whole project.' This strongly distinguishes it from sibling tools like typst_create_project or typst_update_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?

The description provides a crucial usage constraint: it should only be used 'on explicit user request,' which guides the AI agent's intent filtering before invocation.

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, and the description corroborates this by spelling out that the directory is created if missing and existing same-path files are overwritten. That is exactly the risk detail an agent needs before invoking a disk write. It does not cover partial-failure behavior or whether the response reports downloaded files, but the annotation coverage lowers the burden.

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 compact sentences: the operation and its overwrite semantics come first, usage context second. No filler and nothing is 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?

For a two-parameter tool with rich annotations and no output schema, the description covers directory creation, overwrite behavior, and intended uses. The main remaining gap is what the call returns or how failures/partial downloads are surfaced, which matters for a bulk disk write.

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 the schema already explains that 'directory' must be an absolute local path and where 'project_id' comes from. The description adds no parameter-level detail beyond that, 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?

"Download all files of a project into a local directory" states a specific verb, resource, and scope. The 'all files' phrasing implicitly distinguishes it from the single-file sibling typst_read_file, though no sibling is named 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?

It gives concrete use cases (backups, git, local editing) that tell the agent when this is appropriate. It stops short of stating when not to use it or pointing to alternatives such as typst_read_file for a single file.

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 clarifies that ALL files are copied and that the copy may land in a team, which goes slightly beyond the annotations. With annotations already declaring non-readonly, non-destructive, non-idempotent, and open-world, the remaining burden is low, but it doesn't say whether the source is left untouched, what happens on name collision, or what the caller gets back (e.g. the new project id).

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 resource and action come first and the team option is a compact qualifier. It could carry one more clarifying clause without becoming bloated.

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 quiet mutation tool with three params and no output schema, the description covers the core action but leaves key questions unanswered: whether the original is preserved, what the response contains, and any permission or quota constraints. Adequate, not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%: project_id and name are documented in the schema, team_id is not. The phrase "optionally into a team" supplies the missing semantics for team_id, which is genuine added value, but nothing is said about how name defaults if omitted or what team_id format is expected.

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?

"Copy a project (all files) into a new project" gives a specific verb (copy/duplicate) and resource (project), plus the scope of what gets copied. It reads clearly against siblings like typst_create_project, though it never explicitly contrasts with them.

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 only: the agent can infer this is for duplicating rather than creating or downloading a project. There is no explicit when-to-use statement, no exclusions, and no reference to an alternative (e.g. typst_create_project + typst_upload_file).

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?

Adds real behavior beyond the annotations: atomicity ('if one fails, nothing is saved') and concurrency safety ('only the changed span is sent, so concurrent edits by collaborators are preserved'). These are non-obvious traits an agent cannot infer from destructiveHint=false or idempotentHint=false, though failure modes and error surface are not described.

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

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

Four short sentences, each carrying distinct information: match semantics first, then uniqueness rule, then ordering/atomicity, then concurrency rationale. No filler and no repetition of 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?

Covers the essential risk areas for a mutation tool with no output schema: what happens on partial failure, why exact matching matters, and how concurrency is handled. Gaps remain around prerequisites (must the file exist? what happens on a missing file) and whether an edit can create a file.

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 67%, and the description compensates by explaining the uniqueness contract on old_string and the effect of replace_all, which the schema only labels generically ('Exact text to find', 'Replace every occurrence'). Ordering semantics of the edits array are also clarified, though the project_id/path resolution rules are left entirely to 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 ('Replace exact text in a text file') and clarifies the semantics as exact-match find-and-replace including whitespace. It doesn't explicitly contrast itself with the sibling typst_write_file, which is the main ambiguity an agent would face when choosing between them.

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?

Provides operational constraints (unique match required unless replace_all=true, edits applied in order) which implies this is the surgical-edit path. However, it never says when to prefer this over typst_write_file or typst_upload_file, and no exclusions are given.

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 readOnly/idempotent/non-destructive, and the description goes beyond them by enumerating the returned payload (paths, text/binary flags, IDs, counts, share links, membership) — valuable because there is no output schema. It does not warn about payload size for projects with many files.

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 scope first, followed by a dense but purposeful content list. No filler; could be marginally easier to scan if the return list were separated from scope.

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?

Without an output schema, the description carries the return-value burden and does so by listing the response contents. Gaps are minor: no mention of how large responses behave or pointers to sibling tools for narrower reads.

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 project_id (with a format example) and response_format (enum) are already documented in the schema. The description adds nothing param-specific beyond implying a single project, 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?

Specific verb ('Show') plus resource ('one project') with an enumeration of what is returned (files, main file, compiler pin, comment counts, share links, members, invitations). The singular scope distinguishes it from typst_list_projects without naming it 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?

No explicit when-to-use or when-not-to-use statement, and no sibling named. Usage is only implied: 'Show one project' suggests calling it when you already have an ID and need full detail rather than a listing.

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 adds useful behavior beyond annotations by disclosing that typst.app sends the invitation and that user confirmation is required first. It does not cover failure cases such as duplicate invitations, but the key external side effect is surfaced.

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

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

Three short sentences with no filler, and the core action is front-loaded. The confirmation requirement is placed after the purpose, which is an appropriate order.

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 an external invitation side effect and no output schema, the description covers the essential context: what happens and that user approval is needed. It could say more about invited-user status or duplicate handling, but the core call requirements are present.

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 moderate at 67%, with access and project_id described directly in the schema. The description only adds that the invite is sent by email, which does not materially expand on the parameter definitions.

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: invite someone to a project by email. This is clear enough to distinguish it from remove/update member operations, though it does not explicitly name those alternatives.

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 precondition: ask the user before inviting anyone. The invitation-by-email framing also implies the use case, but there is no explicit routing guidance for existing members versus new invitees.

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 readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds genuinely new behavioral context: resolved comments are excluded by default and are surfaced only on request, plus the shape of what comes back (file, line, text, replies) despite 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?

Two short sentences with zero filler; the resource and returned fields come first, and the one non-obvious parameter rule is front-loaded immediately after.

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 usefully sketches the return shape, and it resolves the only undocumented parameter. Minor gaps remain — no pagination or ordering behavior for a list tool that could grow large.

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 67%; project_id and response_format are already documented, but include_resolved has no schema description, and the description supplies exactly that missing semantics (default false, opt-in to resolved). That is a real gain beyond the structured fields.

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 review comments of a project') and even enumerates the returned fields (file, line, commented text, replies). It contrasts implicitly with the write-side siblings (add/reply/resolve/delete_comment) via the 'List' verb, but never names an alternative 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?

Use is implied by the verb, and one usage-shaping rule is given ('Resolved comments only with include_resolved=true'). There is no explicit statement of when to prefer this over typst_get_project or other read tools, and no prerequisites or exclusions.

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 readOnly/idempotent/non-destructive/openWorld, so safety is covered. The description still adds real behavioral context the annotations don't: result ordering (newest first), the project categories included, and that returned IDs are required by other tools — genuinely useful for chaining.

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; listing scope and ordering are front-loaded, the filter rule follows, and the example earns its place by showing a realistic invocation. No redundancy with the title.

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, and the description partially compensates by saying results carry the IDs other tools need, though it doesn't describe the per-project fields or pagination behavior implied by limit/offset. Adequate for a list tool, with a minor gap on return shape.

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 50%: query and response_format are documented in the schema, while limit and offset have no description in either place. The description adds case-insensitive substring semantics for query, which is more than the schema says, but leaves pagination parameters unexplained, so it only partly compensates.

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 plus resource plus scope: 'List typst.app projects: personal, team and shared-with-me, newest first.' An agent can distinguish this from typst_get_project (single project) and typst_search_templates (templates) without opening a 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?

Explains the filtering use case with a concrete example ('Find my thesis project' -> query="thesis") and states a key reason to call it: it returns IDs needed by every other tool. It does not explicitly state exclusions versus typst_get_project, but the intended context 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?

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuine value beyond them by disclosing the polymorphic return behavior (text content, inline images, binaries requiring save_to), which the agent cannot infer from annotations. Missing operational details such as missing-file errors or size thresholds.

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, each carrying distinct information, with the core read behavior front-loaded and parameter hints following. No repetition of the title or schema text and nothing extraneous.

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?

There is no output schema, and the description usefully compensates by explaining the shape of results per file type, which is what an agent most needs here. It is nearly complete, lacking only edge-case behavior (nonexistent path, very large text files) to be fully self-sufficient.

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 a baseline of 3 would be defensible, but the description adds intent beyond the schema text: line ranges are framed as the mechanism for long files, and line_numbers is tied to a specific downstream use (commenting on line ranges), which the schema's 'Prefix each line with its number' does not convey.

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 a file from a project) and immediately explains the three return modes by file type, which is the key disambiguation an agent needs. It does not explicitly name typst_write_file/typst_edit_file as the mutating counterparts, so sibling differentiation is implicit rather than stated.

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 conditional guidance: start_line/end_line for long files, save_to for binaries, line_numbers when planning line-range comments. This is clear usage context for the non-obvious parameters, though it stops short of stating when to prefer a sibling tool (e.g., typst_download_project for bulk retrieval).

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 mark this as destructive and non-idempotent, but the description adds little behavioral context beyond that. It does not describe the effect of removal, permission requirements, reversibility, or what happens to the removed user's access.

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 short sentences with the core action front-loaded and no wasted wording. It is appropriately sized for a simple two-parameter operation.

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

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

The description plus annotations and schema cover the basics needed to call the tool, but for a destructive mutation it omits important context such as side effects, permission constraints, and failure modes. It is minimally adequate rather than complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 50%, and the undocumented user_id parameter is clarified by the description as coming from typst_get_project. The other parameter, project_id, is well documented in the schema with an example.

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: 'Remove a member from a project.' It is clear what the tool does, though it does not explicitly differentiate itself from related sibling tools such as typst_update_member or typst_revoke_invitation.

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 only explains where user_id comes from, not when to use this tool versus alternatives like updating a member or revoking an invitation. Usage is implied by the tool name, but no explicit when/when-not guidance is given.

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 idempotent=true, destructive=false, and openWorld=true, so safety is largely covered. The description adds the useful behavioral caveat that include/import references break after a move, but doesn't cover overwrite behavior, error conditions, or batch failure semantics. With annotations present, credit is moderate.

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 and followed by the key caveat. No 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?

For a 2-param mutation tool with annotations and no output schema, the description is adequate but leaves gaps: whether renames is atomic, what happens if the destination exists, and how file-ID 'from' values behave are unaddressed.

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 50%; the description clarifies that a 'move' is expressed simply as a new 'to' path, which is the key semantic insight beyond the schema's field descriptions. It doesn't explain the 'from' accepting a file ID or batch-array behavior, but adds real value.

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 ('Rename or move files inside a project') and the scope. An agent can immediately distinguish it from siblings like typst_write_file or typst_edit_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?

Says moving is accomplished via a new path, which clarifies the move-vs-rename dichotomy, and warns to update #include/#import paths. However it gives no explicit when-to-use-this-vs-alternatives guidance or prerequisites (e.g., must the destination not exist?).

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 disclose this is a non-read-only, non-idempotent, non-destructive, open-world write operation. The description adds the useful source of 'comment_id,' but does not explain what a reply does to the thread, whether permissions are required, or what a repeated call does beyond the non-idempotent annotation.

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 short sentences with no filler; the core action is front-loaded and the provenance note is compact. It could be slightly more informative without becoming verbose, but it is efficient.

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

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

For a simple three-parameter mutation, annotations cover the safety profile and the description covers the action and comment ID source. However, with no output schema and incomplete parameter coverage, it omits content expectations and return behavior, leaving some gaps an agent might need.

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 only 33%: 'project_id' is described in the schema, while 'comment_id' and 'content' are not. The description usefully explains where 'comment_id' comes from, but it says nothing about 'content' format (plain text, markdown, limits) and adds little for 'project_id' beyond the schema example.

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 and resource: 'Reply to a comment thread.' This clearly separates it from non-thread operations, though it does not explicitly contrast with the sibling tool 'typst_add_comment' beyond the word 'thread.'

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 gives useful provenance for 'comment_id' ('comes from typst_list_comments'), implying it should be called after listing comments. However, it does not say when to choose this over 'typst_add_comment' or 'typst_resolve_comment,' nor does it mention preconditions or exclusions.

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 adds the useful fact that this is a reversible toggle rather than a one-way action, but says nothing about permissions, what happens if the comment is already resolved, or error behavior on a missing thread.

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 primary action comes first and the less common reverse case follows. 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?

Adequate for a simple idempotent toggle with no output schema, and the reversible-state nuance is captured. However, an agent still doesn't know whether resolving requires ownership or specific project permissions, nor what a failure looks like on an unknown or already-resolved comment.

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 only 33%: project_id is documented but comment_id and the resolved boolean are not described at all in the schema. The description compensates for the most consequential gap by explaining that resolved=false reopens rather than resolves, which is exactly the non-obvious semantics of the 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?

States a specific verb (mark resolved) and resource (comment thread), and adds the inverse operation (reopen) in the same sentence. It is distinguishable from siblings like typst_delete_comment or typst_reply_comment without opening a schema, though it doesn't name them 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 implied by the action itself – you call this to resolve or reopen a thread – and the resolved=false case is spelled out. There is no explicit when-not-to-use guidance or pointer to a sibling like typst_delete_comment for permanent removal.

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, so safety profile is clear. The description adds useful context that only pending invitations are affected and that the invitation is identified by email, but it doesn't explain what happens if the invitation is not pending or what the response looks like.

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 no wasted words. It efficiently states the core action and identifier.

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 tool with rich annotations (destructive, idempotent) and no output schema, the description is largely complete. It could mention project_id explicitly, but the schema already provides that context, so the agent has enough to call the tool 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 50%: project_id is described in the schema, but email only has format constraints. The description's 'by email' adds the semantic that email identifies the invitation to revoke, partially compensating for the gap, but it does not mention project_id or how email and project_id interact.

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 ('Withdraw') and resource ('pending invitation') with the identifier ('by email'), making the action clear. It does not explicitly differentiate itself from siblings like typst_remove_member or typst_invite_member, though the 'pending' qualifier implicitly distinguishes 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 provides no guidance on when to use this tool versus alternatives or when not to use it. It only states the action, leaving the agent to infer that this is for cancelling invitations rather than removing existing members or deleting projects.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds useful behavioral context beyond that: results reflect 'latest versions' and the returned name is the input to project creation, closing the search-to-create loop. It doesn't mention result ordering or network/rate-limit behavior, which is a minor gap.

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 plus two examples, with the core purpose front-loaded and the workflow handoff immediately after. The examples are short and directly earn their place by demonstrating query construction rather than restating the 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 2-parameter, zero-required read tool with no output schema, the description covers purpose, query construction and next steps. The only shortfall is that it never says what comes back (e.g., names plus descriptions), which matters somewhat given there is no output schema to fall back on.

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 50% — query is documented but limit has no description at all. The description compensates well for query by giving concrete mappings ('IEEE paper' -> query='ieee'), clarifying that natural-language phrases should be reduced to keywords. The undocumented limit parameter is left unaddressed, keeping this below a 5.

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 (search) and resource (Typst Universe templates), plus the scope 'latest versions' and the intended outcome ('to start a project from'). No sibling does anything comparable, and the description explicitly names the downstream tool typst_create_project, making the role obvious.

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?

Clearly says when to use it (starting a project from a template) and what to do next (pass the chosen name to typst_create_project). It doesn't need to name alternatives since no sibling search tool exists, but there's no explicit statement of when not to use it, such as when you already know the template 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 the mutation is idempotent and non-destructive. The description adds meaningful context beyond that: omitted flags remain unchanged, and the call returns the current links, which matters because there is no output schema. It does not mention permission requirements or security implications of enabling write links, but the added partial-update and return behavior is substantive.

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 well-structured sentence with no wasted words. It front-loads the mutation and then adds the return and partial-update behavior efficiently.

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 small mutation tool with no output schema, the description covers what changes, what is left unchanged, and what is returned. It lacks explicit permission details and a fuller explanation of each access mode, but the key behavioral facts needed to call it correctly are present.

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 only 25%, but the description compensates by naming the read, review, and write flags and explaining that omitted flags stay unchanged. Project_id is not described in the text, though the schema already documents it with a retrieval hint.

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 ('Turn ... on or off'), a specific resource ('anyone-with-the-link URLs'), and the exact access modes affected ('read, review and write access'). This clearly distinguishes the tool from member-management siblings such as typst_invite_member and typst_update_member.

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 implies when this tool is appropriate by focusing on anyone-with-the-link access rather than member invitations, but it does not explicitly name alternatives or state when not to use it. The note that omitted flags stay unchanged is a useful usage constraint for partial updates.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true), so the behavioral bar is lowered. The description adds little beyond that: it does not state required permissions, what happens if the user is not yet a member, or whether the change notifies anyone.

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 short sentences, front-loaded with the action and followed by the one piece of sourcing context. Nothing is redundant.

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 three-parameter mutation with annotations covering safety, the description is adequate but thin. A caller still lacks information about preconditions (must the user already be a member?) and permission requirements for editing member access.

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 67%: access and project_id already have good inline descriptions, but user_id is undocumented in the schema. The description compensates by stating user_id comes from typst_get_project, resolving the one blind spot with actionable guidance.

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 ('Change') and resource ('member's access'), clearly separating it from typst_invite_member and typst_remove_member in the sibling set. It does not explicitly name those siblings as alternatives, but the operation is unambiguous.

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 implies usage through the pointer that user_id comes from typst_get_project, which tells the agent where to source the identifier. However, it gives no explicit guidance on when to choose this over invite_member/remove_member, nor whether the target user must already be a member.

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 establish that this is a non-read-only, idempotent, non-destructive mutation. The description adds useful behavioral context by explaining that the main file is the previewed/compiled file and that the pinned version is used by the web app.

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 lists the three supported update operations without any 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?

For a simple update tool with annotations covering safety and idempotency and a schema covering most parameters, the description provides enough context to invoke it correctly. It could still be improved by stating that omitted fields remain unchanged.

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 75%, and the schema itself documents project_id, main_file, and pinned_version. The description maps operations to parameters and adds context for main_file and pinned_version, but it does not clarify the name parameter or fully compensate for the remaining schema gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names specific project-settings operations: renaming, setting the main file, and pinning the compiler version. It is clearly about updating an existing project, but it does not explicitly distinguish itself from sibling tools such as typst_create_project or typst_get_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?

The listed operations imply when to use the tool, e.g. to rename a project or change its main file. However, there are no explicit when-not conditions or references to alternative tools for related project or file changes.

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, and the description adds useful specifics: existing files with the same path are replaced, and hidden files/folders are skipped. It does not discuss permissions or return behavior, but it goes beyond the annotations where it matters most for a destructive 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?

The description is front-loaded with the core action, then states replacement and hidden-file behavior, followed by a compact example. Every sentence contributes relevant information without unnecessary verbosity.

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 rich annotations, full parameter schema coverage, and no output schema, the description provides enough behavioral context to invoke the tool correctly. It could be slightly more complete by explaining what happens on success or failure, but the essential overwrite/skip semantics are covered.

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 three parameters. The description still adds semantic value through the example mapping local_path="/home/me/figures" to remote_path="figures", clarifying directory-prefix usage beyond the schema text.

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: uploading a local file or whole folder into a project. It is clear and concrete, including examples of file types, but it does not explicitly distinguish this tool from siblings such as typst_write_file or typst_edit_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?

Usage is implied by the local-file/local-folder framing, and replacement/skip behavior is noted, but there is no explicit guidance on when to use this tool instead of typst_write_file or other file tools. The agent must infer the alternative from the tool name and description.

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 readOnly, idempotent, non-destructive, open-world behavior, so safety is covered. The description adds non-annotation context by disclosing the returned content (account identity plus workspaces and their IDs), which is valuable since there is no output schema; it does not discuss auth failure modes or the shape of the response beyond that.

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 short sentences, zero filler. What the tool returns is front-loaded and the actionable follow-up (team IDs feed typst_create_project) comes second.

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 discovery tool with no output schema, the description covers what an agent needs: it names the identity and workspace data returned, notes team IDs are included, and connects that output to the tool that consumes it.

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 and the baseline of 4 applies. No parameter claims are made that could mislead.

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 ('Show the signed-in typst.app account and its workspaces') and scopes the result to personal plus team workspaces with their IDs. No sibling tool does anything similar, so it is unmistakable in the toolset.

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 tells the agent the downstream purpose: 'Use the team IDs for typst_create_project', which effectively defines when to reach for this tool. It stops short of naming exclusions or prerequisites (e.g., what happens when not signed in), so it is clear context rather than a full when/when-not rule.

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, so the safety profile is covered; the description still adds real context: the write replaces the entire content (what gets destroyed), folders are auto-created, and collaborators see the change live in the web editor. It stops short of stating permission/auth requirements or that a new file is created when the path 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?

Three short sentences, front-loaded with the core action, then the sibling routing rule, then the folder-creation aside. 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 destructive whole-file write with no output schema and full parameter coverage, the description covers the essentials: overwrite semantics, live-collaboration side effect, implicit directory creation, and the correct alternative. Only authorization/precondition behavior for a nonexistent path or ID-based path is unaddressed.

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 path/content/project_id are already documented in the schema, making 3 the baseline. The one added semantic is that the path implicitly creates folders, which is genuinely useful but only touches a single 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?

States a specific verb and resource ('Create a text file or replace its entire content') and distinguishes itself from typst_edit_file, typst_upload_file and typst_read_file by naming the partial-edit sibling directly. An agent can pick between write and edit 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?

Names the alternative (typst_edit_file) and the exact condition that selects it ('changes to part of an existing file'), implying whole-file rewrites belong here. No exclusions are left to inference for the main confusion risk among the file tools.

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