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

Annotations already indicate the operation is not read-only, not idempotent, and not destructive, so the description doesn't need to restate those. It does add the requirement TYPLEAF_SESSION and the engine dependency, but it does not disclose potential side effects like overwriting files, whether compilation is synchronous, or how failures are reported—gaps the annotations don't fill. The description adds some value but not rich behavioral context.

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

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

Three sentences with no filler: the action, the return value, the engine source, and a prerequisite are all front-loaded. Every sentence earns its place without redundancy.

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 compilation trigger, the description covers the core action, return type, and engine selection. It omits potential asynchronicity, error behavior, or how to retrieve logs (download_log exists), and there is no output schema to fall back on. Still, for a simple trigger it is largely sufficient, so a 4 is warranted.

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 description for project_id is 100% covered and highly detailed (format, how to obtain, what not to use). The tool description does not add any additional parameter semantics beyond the schema, so with high schema coverage 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 clearly states the action ('Trigger PDF compilation') with a specific resource ('on Typleaf') and explicitly lists the output ('compilation status and output file list'). It also distinguishes itself from the sibling set_compiler by noting the engine comes from the project's compiler setting, so an agent can tell them apart.

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 points to set_compiler as the source of the engine, implying set_compiler is used for that purpose, and states it works for both Typst and LaTeX. However, it does not explicitly contrast with local file-reading tools or download_pdf, though the parameter schema (not the description) covers when to avoid remote tools. The description itself gives decent context but not exhaustive 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?

All annotations are false, giving no safety signal, so the description carries the burden. It does disclose notable side effects: auto-creating parent folders and immediately committing and pushing. Yet it does not disclose behavior when the file already exists, whether existing content may be overwritten, or what happens if the commit/push fails.

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 tight sentences with no filler. The primary action is front-loaded, and the two behavioral side effects are stated immediately afterward, making it easy to parse.

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 core action, location, and side effects are covered, and the schema fills in parameter details completely. However, with no output schema, the description does not mention return value or success/failure information, and duplicate-file handling is absent—gaps for a mutating tool that auto-pushes.

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 documents all four parameters, including a detailed explanation of project_id. The tool description itself adds no additional parameter-level meaning, 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 opens with a specific action and resource: 'Create a new file in a Typleaf project.' It also notes auto-creation of parent folders, which clarifies scope. This differentiates it from siblings like edit_file, rewrite_file, and update_section, which all imply acting on existing content.

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 project_id parameter description provides clear usage boundaries: only use Typleaf tools for explicit Typleaf projects, never for local file I/O, and prefer local read/grep tools when a checkout exists. However, the description does not explicitly state when to choose create_file over edit_file or rewrite_file, so it stops short of a 5.

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 only indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the description carries the burden for operational disclosure. It adds the TYPLEAF_SESSION requirement and the compiler failure behavior, which are valuable beyond the annotations. It stops short of describing success returns or side effects, but the disclosed information is substantial.

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, each earning its place. The first states the core purpose, the second delivers the most essential usage caveat and authentication requirement. No filler or redundancy—ideal length and structure.

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 create operation with only two parameters and no output schema, the description covers everything an agent needs: the session requirement, the compiler selection guidance, and the failure mode. It is complete for safe and correct invocation.

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%, providing base descriptions for both parameters. The description adds significant value for the compiler parameter by explaining its default and the critical pitfall (confusing TeX errors), which the enum alone does not convey. For the name parameter, no additional nuance is added, but that is acceptable given its simplicity.

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 identifies the action: 'Create a new blank Typleaf project'. It specifies the resource type and even distinguishes from other tools by mentioning the web API context. It also names the key compiler option upfront, making it easy for an agent to understand what this tool does.

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 strong guidance on when to use compiler='typst', explaining the default pdflatex and the specific failure mode for .typ files. However, it does not explicitly compare against alternative tools like set_compiler (for modifying an existing project's compiler) or list_projects, leaving some inference required for an agent to know this is only for initial creation.

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 readOnlyHint=false, so the description correctly aligns with that intention. It adds the behavioral detail that the deletion 'commits and pushes immediately,' which is useful beyond the annotation. However, it does not disclose potential consequences like irreversibility or permission requirements, but the destructive annotation partiall covers 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?

The description is a single concise sentence that states the core action and an important side effect (commits/pushes). It avoids fluff and is easy to parse, though it is arguably too sparse to be fully self-sufficient.

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 tool is destructive and has three parameters, yet the description omits explanation of the optional commit_message, does not warn about irreversibility beyond the annotation, and provides no context about how the deletion affects the project. Given low schema coverage and no output schema, an agent would not know the full impact of calling this tool.

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

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

Schema description coverage is only 33% (only project_id is described). The description does not mention commit_message at all, leaving its purpose and optionality unexplained. Since the description is the only other source of meaning, it should compensate for the sparse schema, but it 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?

The description clearly states the action: 'Delete a file from the project.' It identifies the resource (file) and scope (project), making the tool's purpose unambiguous. It does not explicitly contrast with sibling tools like edit_file or rewrite_file, but the delete verb is distinct enough to avoid confusion.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, caution about destructive operations, or when to prefer local file tools. The only contextual hint (about Typleaf projects) appears in the schema's project_id description, not in the tool 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?

The description reveals key behaviors beyond annotations: it parses Typst logs into a compact list, returns raw logs for LaTeX, and requires TYPLEAF_SESSION. Annotations only say readOnlyHint=false, idempotent=false, destructive=false, which are not contradicted but also not informative. The added behavioral detail is valuable.

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 dense sentence with zero fluff. It front-loads the action, then explains the Typst/LaTeX difference, and ends with the session requirement. Every word earns its place.

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

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

It covers the core action, the two project-type behaviors, and a prerequisite. With no output schema, the description does indicate return format (compact list vs raw). It lacks mention of failure modes or session expiration, but for a 2-parameter read-like tool, it is sufficiently complete.

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

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

The schema descriptions cover both parameters (raw and project_id) exhaustively, including the default and format. The tool description adds no parameter-specific guidance beyond contextual behavior (e.g., raw for LaTeX), so it does not elevate beyond the schema baseline.

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

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

The description uses a specific verb ('Fetch') and a clearly defined resource ('compilation log from Typleaf'). It also distinguishes between Typst and LaTeX behaviors, which immediately separates it from sibling tools like download_pdf or download_source. The purpose is unmistakable.

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 clearly states the tool is for compilation logs and gives context for both project types, which tells an agent when to reach for it. However, it does not explicitly name alternatives or say 'use X instead', but the resource is distinct enough that an agent can infer when to use it.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=true. The description adds context about the prerequisite (compile_project) and authentication (TYPLEAF_SESSION), which goes beyond annotations. However, it doesn't elaborate on destructive behavior (e.g., overwriting existing files) or return values. Since annotations cover the safety profile partially, a 3 is appropriate.

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 waste. The core action is front-loaded, followed by essential prerequisites. Every sentence earns its place.

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

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

For a simple 2-parameter tool with no output schema, the description covers the essential steps: what it does, what to call first, and what authentication is required. It doesn't mention error conditions or return values, but those are typically not needed for a download operation. The description is sufficiently complete for an agent to call 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 description coverage is 100%: both project_id and output_path have detailed descriptions in the schema, including the full context for project_id. The tool description itself adds nothing about parameters. Baseline 3 is correct when the schema handles parameter semantics.

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 ('Download'), a resource ('the compiled PDF'), and a destination ('to a local path'). It clearly distinguishes itself from siblings like download_source and download_log by specifying 'compiled PDF', making the tool's purpose 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 provides explicit usage guidance: 'Call compile_project first' and 'Requires TYPLEAF_SESSION.' This tells the agent when and under what conditions to use the tool. It doesn't explicitly mention alternatives or when not to use it, but the prerequisites are clearly stated.

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, but the description adds valuable behavioral context: requires TYPLEAF_SESSION, creates the directory if missing, and fails on non-empty directory unless overwrite=true. This goes beyond annotations by detailing the failure condition and the overwrite trigger. It doesn't contradict any 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?

Two sentences with zero fluff. The core purpose is front-loaded, followed by two critical behavioral constraints and a prerequisite. Every sentence earns its place, and the structure makes scanning easy.

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 covers the key operational aspects: action, prerequisites, failure modes, and overwrite behavior. It doesn't describe the return value or what happens on success, but with no output schema and a destructive/idempotent annotation set, this is a minor omission. The detailed project_id guidance in the schema further fills context. Could mention success behavior but is otherwise complete.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters. The main description adds no extra parameter semantics beyond what the schema provides. The project_id description is exceptionally rich, but that's already in the schema. Baseline 3 is appropriate because the schema carries the load.

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 a specific verb ('Download') and resource ('project source') with an explicit action ('extract it into a local directory'). It also specifies unique behaviors (directory creation, non-empty failure) that distinguish it from the sibling download_source_zip, which likely skips extraction. Purpose 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 itself doesn't name alternatives, but the project_id parameter schema provides strong usage guidance: only for Typleaf projects, never for general local file I/O, prefer read/grep if a local copy exists, and always call list_projects when unsure. This embedded guidance covers when-to-use and when-not-to-use, though it doesn't explicitly contrast with download_source_zip. Slight gap in explicit sibling differentiation prevents a 5.

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 a useful authentication prerequisite, TYPLEAF_SESSION, which annotations do not express. However, despite destructiveHint=true it never says whether an existing output_path will be overwritten or otherwise affected, so the agent cannot anticipate the destructive consequence accurately.

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 ('Download the full project source as a ZIP file to a local path') and followed by the only prerequisite. No filler or repeated schema data.

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 a detailed schema, a clear auth note, and annotations covering idempotence and destructiveness, an agent has most of what it needs to call the tool correctly. It would be more complete if it stated the overwrite behavior and what the tool returns, but those gaps are minor for a simple file-download operation.

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 description adds no parameter-level detail, but schema_description_coverage is 100%, so the schema already carries the load. The project_id description is particularly rich with remote ID constraints and local-path exclusions, so the 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?

States a concrete action ('Download'), a precise resource ('the full project source'), a format ('ZIP file'), and a destination ('local path'), so an agent knows exactly what this tool does. The ZIP qualifier separates it from siblings like download_pdf, download_log, and download_source.

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 project_id parameter description provides explicit when/when-not guidance: only for remote Typleaf projects, never for general local file I/O, prefer local read/grep if a checkout exists, and call list_projects first if unsure. This tells an agent when to invoke the tool and what to do instead, which is more than enough to avoid misrouting.

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 readOnlyHint=false, indicating a write and potentially destructive operation. The description adds the important side effect 'Commits and pushes immediately' and the constraint that old_string must match exactly once, which are valuable beyond annotations. However, it does not disclose error handling (e.g., multiple matches) or whether the file must exist, so transparency is adequate but incomplete.

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

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

Two sentences with no wasted words. The core function 'Surgical search-and-replace edit' is front-loaded, followed by the critical uniqueness constraint and immediate commit/push side effect. Every sentence earns its place, making it highly concise and well-structured.

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 omits any mention of return values or errors (e.g., what happens if old_string is not found or matches multiple times). Given the destructiveHint and lack of output schema, an agent might benefit from knowing failure modes. However, the commit/push behavior and uniqueness constraint are covered, and the project_id schema description provides remote-project context, so completeness is moderate.

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 60% with project_id having a detailed description. The description adds semantic value by stating that old_string must match exactly once, which is more specific than the schema's 'Exact text to find'. It does not clarify commit_message or other parameters, but the primary constraint is useful. Since schema partially covers parameters, the score is moderate.

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 identifies the action as a surgical search-and-replace edit on a file, which distinguishes it from broader operations like rewrite_file or create_file. However, it does not explicitly name alternative sibling tools, so it lacks overt differentiation despite the clarity of the core function.

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 like rewrite_file or update_section. The description notes that it commits and pushes immediately, which is a behavior, not a usage guideline. It does not specify preferred scenarios or exclusions, leaving the agent to infer suitability.

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 annotation readOnlyHint: true already covers the non-destructive nature, so the description does not need to repeat that. However, it also does not add any additional behavioral context, such as truncation behavior, default refs, or performance implications. The description essentially restates the tool's purpose without disclosing any traits beyond the annotation, so it provides only minimal added value.

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 filler, and the primary operation is front-loaded. The second sentence adds a clear use case. Every word earns its place, making this an exemplary concise 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 6-parameter tool with a read-only annotation and full schema coverage, the description is largely sufficient. It states the core operation and a typical use case. The only minor gap is it does not explicitly mention that the tool operates on a remote Typleaf project (though the project_id parameter description covers this), nor does it describe the output format, which is arguably implied by 'diff'. Overall, the description, combined with the schema and annotation, provides enough context for correct invocation.

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% with all six parameters documented, including detailed explanations for project_id (which clarifies remote usage). The tool description itself adds no parameter-specific meaning beyond what the schema already provides, 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: 'Get a git diff between refs or the working tree.' This clearly identifies the operation and scope, and it is distinct from all sibling tools (none of which handle git diffs), so an agent can easily differentiate it without inspecting 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?

The phrase 'Useful for reviewing recent changes' provides a clear context for when to use the tool, but it does not explicitly state when not to use it or mention alternatives. There are sibling tools like status_summary and list_history that might overlap conceptually, and the description does not clarify how to choose between them. The usage guidance is implied rather than explicit.

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 are all false, so the description must disclose behavior. It does: 'Compile the project' indicates non-read-only action, and 'Requires TYPLEAF_SESSION' states an authentication requirement. It also explains the method for each engine. This adds valuable context beyond annotations. It could be more explicit about side effects, but the compilation action is clearly implied.

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 sentences with no filler. The primary purpose is front-loaded, followed by usage guidance and engine-specific behavior. Every sentence earns its place, and it is compact yet complete.

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 a single parameter, a fully descriptive schema, and clear behavioral notes, the description covers purpose, usage, and method. It states it reports a total page count, so the return value is implied. No significant information needed for correct invocation 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?

The schema description covers 100% of the parameter and provides detailed guidance on what project_id is and when to use it, including avoiding local paths and preferring list_projects. The tool description adds nothing about the parameter itself, 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: 'Compile the project and report the TOTAL number of pages in the PDF.' It clearly distinguishes the tool from siblings like get_sections or section_page_map by focusing on page count. The intended use cases are explicitly named, leaving no doubt about what the tool does.

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

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

The description provides clear use cases: answering 'how many pages is it?' or driving a fill-exactly-N-pages editing loop. It also notes engine-specific behavior (LaTeX vs. Typst). However, it does not mention when not to use this tool or point to alternatives (e.g., local file tools), though the parameter schema covers those exclusions. Still, the description itself gives sufficient context for correct selection.

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 annotation readOnlyHint=true already signals a safe read operation, and the description's 'Get' is consistent. The description adds valuable behavior beyond the annotation: it discloses support for .typ and .tex and explains that the parser is chosen by file extension. It does not discuss error handling (e.g., missing section), but given the read-only nature this is acceptable.

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 exactly two sentences: the first states the primary purpose, the second adds the format support and parser selection. It is front-loaded, succinct, and contains no fluff or redundancy.

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-only tool with no output schema, the description adequately conveys that the return is the full section content and notes the supported file types. It does not cover edge cases like exact title matching or error behavior, but these are minor given the tool's scope.

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 section_title have descriptions; file_path does not). The tool description adds no parameter-specific information, so it relies entirely on the schema. With coverage above 50%, the baseline is 3, and the description does not compensate for the missing file_path description.

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

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

The description clearly states the action ('Get the full content of a specific section') and the resource (a section by title), and specifies supported formats (Typst and LaTeX). It implies a distinction from siblings like get_sections (listing sections) and read_file (whole files), but does not explicitly name 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?

The tool description provides no guidance on when to use this tool versus alternatives. It does not mention that this is for section-specific content rather than listing sections or reading entire files, nor does it advise when to prefer local file tools. The only usage context is buried in the project_id parameter description, not in the tool description itself.

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 readOnlyHint annotation already signals read-only operation, so the bar is lower. The description adds value by specifying the exact payload returned (types, titles, hierarchy levels, content previews) and noting that parser selection is based on file extension. No contradictions or missing behavioral disclosures 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?

The description is three sentences, front-loaded with the core purpose and then providing format-specific details and return contents. No redundant phrases or unnecessary clarifiers; every sentence contributes to understanding the tool's behavior.

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 two parameters, both required, and no output schema, the description adequately explains what the tool does, what it returns, and how it selects the parser. The project_id is fully documented in the schema, and the description covers the return structure enough for an agent to know what to expect. Nothing critical is missing for correct invocation.

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%: both file_path and project_id have detailed descriptions in the input schema. The tool description does not add substantial meaning beyond what the schema already provides—it repeats the file type support that is already in file_path. The project_id description in the schema is especially thorough, covering remote vs local context and how to obtain it. Thus the description adds marginal value over the schema, placing it at baseline 3.

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 tool parses a source file and extracts heading structure, naming both supported formats (Typst and LaTeX) and the output components (types, titles, hierarchy levels, content previews). It distinguishes itself from siblings like get_section_content (which likely fetches one section) and read_file (which reads raw content) by focusing specifically on the heading outline.

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 explains the context of use (parsing heading structure) but does not explicitly contrast with alternatives or state when not to use it. It gives clear context on file type selection and what it returns, which is sufficient for a tool that is primarily a straightforward parse-and-extract operation. The absence of explicit alternative routing is a minor gap, not a misleading one.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful context that the tool operates on a REMOTE Typleaf project rather than local files, which is a meaningful behavioral trait. However, it does not disclose details like recursion behavior, sorting, or response shape, so it offers only modest value beyond the 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 a single sentence with no wasted words. It front-loads the action and the optional filter immediately, keeping the top-level description concise while the schema carries the detailed parameter semantics.

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 read-only annotation, only two parameters, and a richly documented schema, the definition is complete enough for an agent to select and invoke the tool correctly. The project_id guidance covers the main failure mode (confusing a remote Typleaf project with a local path), and the extension filter is clearly explained. An output schema would be nice but is not required for correct invocation here.

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 both parameters are thoroughly documented in the schema, especially project_id with its pattern, example, and warnings. The tool description itself adds no parameter meaning beyond what the schema already provides, so the baseline of 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?

The description clearly states the verb ('List'), the resource ('files in a Typleaf project'), and the optional filter ('by extension'), so an agent immediately knows the tool's function. It does not explicitly name sibling tools like search_files or list_projects to disambiguate, but the scope is specific enough that the purpose is not ambiguous.

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 project_id parameter description provides explicit usage guidance: these tools should only be called for remote Typleaf projects, never for general local file I/O, and local copies should be handled with standard read/grep tools. It also instructs the agent to call list_projects first when unsure, which directly supports correct tool selection.

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 annotation readOnlyHint:true already establishes this as a safe read operation, and the description's 'Show' is consistent with that. The description adds no additional behavioral context such as pagination limits, default ordering, or that it returns remote data—all of which could be useful but are not disclosed. Since the description carries little burden beyond confirming the read-only nature, a 3 is appropriate.

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, direct sentence with no filler. It front-loads the core action and object, and there is zero waste. The structure is ideal for quick agent parsing.

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 5 parameters and no output schema, the description is quite sparse—it does not mention the output format, pagination, or that it operates on remote repositories. However, the parameter descriptions (especially project_id) carry substantial contextual weight, and the name 'list_history' is self-explanatory. The description is adequate but leaves some behavioral details (e.g., result shape, default limit limitations) to inference.

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% (all 5 parameters have descriptions). The tool description adds no parameter-specific meaning, but the schema itself thoroughly documents limit, since, until, file_path, and especially project_id (which includes extensive guidance on usage and differentiation from local paths). At high coverage, the baseline of 3 is met without extra description.

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

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

The description clearly states a specific verb ('Show') and a resource ('git commit history') scoped to 'the project'. It unambiguously identifies a read operation for commit history, which none of the sibling tools (status_summary, get_diff, etc.) appear to duplicate, so it differentiates well.

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 tool description itself offers no guidance on when to use it or when to prefer an alternative. It does not mention that it operates on remote Typleaf projects only, nor does it warn against using it for local I/O—that guidance exists only in the project_id parameter description, not in the tool-level description. An agent gets minimal context on appropriate invocation 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?

Annotations already declare readOnlyHint=true, and the description reinforces it. The description adds the session requirement and the return format (names and IDs), which is helpful but minimal. No contradiction.

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

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

Two concise sentences. The first states the action and prerequisite, the second explains the return value and its utility. 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?

For a zero-parameter list tool with no output schema, the description covers the essential information: what it lists, what it returns, and how to use it. It's complete for its simplicity.

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 has zero parameters, so schema coverage is 100%. Description doesn't need to elaborate on parameters; the baseline of 4 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?

Clearly identifies the operation (List), the resource (projects), and the scope (all on the instance). It also explains the output purpose, distinguishing it from other project-related tools like create_project or project_info.

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?

Specifies the prerequisite TYPLEAF_SESSION and explains how the output can be used ('use any ID with other tools'), giving context for when to call. It does not explicitly exclude alternatives, but the intended usage 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 do not indicate read-only or destructive behavior, so the description carries the burden. It discloses the requirement for TYPLEAF_SESSION, the coarser resolution for Typst, and the lack of anchors in template bodies — valuable behavioral context. It does not explicitly state it is a read operation, but the nature of 'Find' suggests that without contradicting annotations.

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 paragraphs, front-loaded with the main purpose and output. Each sentence adds value: the return format, the file omission, the capability contrast, and the backend/limitations. It is concise without being terse.

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 of this complexity, the description covers: what it does, output details (page and bounding box), parameter override behavior, backend differences (SyncTeX vs Typst map), limitations of Typst results, and a required session variable. There is no output schema, so it appropriately explains return values. Missing error handling is minor for this context.

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 covers all parameters with detailed descriptions (100% coverage), so baseline is 3. The description adds extra meaning by explaining the return format (PostScript points, v measured from top) and the behavior of omitting `file` to use compile root. This goes beyond the schema's parameter notes and clarifies usage.

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 a specific verb ('Find'), resource ('given source line' in 'compiled PDF'), and the output (page number and bounding rectangles). It also distinguishes itself by noting it is the 'element→page-position capability the source parser cannot provide,' which separates it from source-content 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?

It gives context for when to use it (when mapping source elements to PDF position) and explicitly contrasts with the source parser. It does not name a specific alternative tool but implies no other tool provides this capability. The mention of the Typst coarse results and template limitations also helps set expectations.

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 the tool as read-only. The description adds valuable behavioral context: it is cheap, performs 'one file listing,' does not compile, and is safe to call before other actions. It also discloses what kind of information the agent will receive, making side effects and cost expectations transparent.

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 only two sentences but packs in purpose, output contents, cost, timing, and decision guidance. Every clause earns its place, and the most important directive ('Report what KIND of project... before doing anything else') is front-loaded.

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 covers what the tool returns at a high level (format, root, count, bibliography files), when to call it, and what it costs. There is no output schema, so a bit more specificity about the exact shape or possible values could help, but the listed outputs are sufficient for an agent to call and interpret the tool correctly in practice.

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%, with a detailed explanation of project_id including format, source (list_projects / project URL), and exclusions (not a filesystem path or project name). The description does not add parameter-level semantics, but with full schema coverage 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 names a specific verb ('Report'), the resource ('project'), and the exact scope: project format (Typst vs LaTeX), likely compile root, source file count, and declared bibliography files. This clearly distinguishes it from siblings like list_files or status_summary by focusing on project-kind identification rather than generic listing or status.

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 says 'Call this first' and gives the triggering condition: 'when you do not already know the project's format.' It also explains practical value (choosing `= Heading` vs `\section{}`). However, it does not name specific alternative tools or describe when one of those would be preferred, so it stops short of full alternative comparison.

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 annotation readOnlyHint=true already establishes the read-only nature. The description adds the remote-vs-local distinction, but does not disclose any other behaviors like authentication, error patterns, or return encoding. Since the annotation covers safety, a 3 is appropriate for the limited extra context provided.

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 states the core function and quickly points to the schema for parameter specifics, which is ideal for this simple tool.

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 is sufficient for a straightforward read operation. The schema covers parameter details, the annotation covers read-only safety, and the description plus schema collectively tell the agent what it does and when to use it. No output schema is needed since the return value is obviously the file contents.

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 file_path and project_id are already fully described in the schema (with particularly thorough detail on project_id). The tool description itself adds no parameter-level information, so it meets the baseline of 3 without compensating for any 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 clearly states the verb 'Read' and the resource 'file from a Typleaf project', which distinguishes it from sibling write tools like edit_file, rewrite_file, and delete_file. The scope is specific (Typleaf project, not local files) and instantly actionable.

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 explicit when-to-use guidance: only when the user asks for Typleaf project work, never for general local I/O, and prefer local read/grep tools if the project is checked out locally. It also instructs to call list_projects first when unsure, which covers the alternative flow.

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 readOnlyHint=false, so the description doesn't need to restate that. It adds valuable behavioral context beyond annotations by specifying that the operation 'commits and pushes immediately', which is a significant side effect an agent should know. This goes beyond what annotations convey.

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 extremely concise at two short sentences, with the primary action ('Replace entire file contents') front-loaded and no filler. Every word adds value, making it highly scannable for 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?

For a destructive operation that commits and pushes remotely, the description is under-specified. It does not clarify how commit_message is handled when omitted, what happens if the file does not exist, or how file_path should be interpreted relative to the project root. The minimalism leaves an agent guessing on crucial execution details.

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?

With 50% schema coverage, the description should compensate for undocumented parameters like file_path and commit_message, but it doesn't. It only implicitly ties to content via 'replace entire file contents'. No guidance is given on file_path format or commit_message requirements, leaving those 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?

The description clearly states it replaces the entire file contents, which is a specific verb+resource. It also notes immediate commit/push behavior, distinguishing it from partial editors like edit_file. However, it does not explicitly contrast with similar sibling tools like write_files, so it lacks full differentiation.

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 is given on when to use this tool versus alternatives. The description only states what it does without mentioning scenarios like 'prefer edit_file for partial changes' or 'use create_file for new files'. The project_id schema description gives general context for Typleaf tools, but not about this specific tool's usage.

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

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

Annotations declare readOnlyHint=true, and the description adds behavior beyond that: it returns file/line/matching line grouped by file, skips binary files, and caps results with the cap reported. This prevents misinterpreting truncated results as complete, which is valuable operational context not present in the annotations.

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 paragraphs with zero filler. The first sentence states the tool's core function; the second justifies its superiority over an alternative; the third explains the return format and cap behavior. Everything earns its place and is front-loaded.

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 read-only search tool with no output schema, the description discloses all necessary call-time knowledge: return format, grouping, binary skipping, and truncation reporting. Combined with the detailed project_id guidance in the schema, an agent has everything needed to invoke and interpret results 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?

All 6 parameters have full schema descriptions (100% coverage), so the description itself adds no parameter-level detail beyond what the schema already provides. The pattern escaping example and path_glob example live in the schema, not the description. Per the rubric, this is a baseline 3.

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 opens with a specific verb-resource pair ('Regex search across every text file in the project') and immediately names the two canonical use cases. It also distinguishes itself from the list_files + read_file alternative, making its unique role among siblings 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?

Explicitly states when to use ('which files call X?', 'where is Y defined?') and why it's preferable (one request vs. per-file round trips that pull whole documents). The project_id parameter description reinforces invocation rules (only for remote Typleaf projects, prefer local tools when a local copy exists, and list_projects first if unsure).

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 all annotations set to false (not read-only, not idempotent, not destructive), the description carries the full burden of behavioral disclosure. It reveals that compilation is triggered ('Compile once'), exposes a race condition ('can race the server's build eviction'), notes format-specific request counts, and requires a session ('Requires TYPLEAF_SESSION'). This is substantive context beyond the annotations, earning a 4.

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 purpose, then usage, then cost/behavioral caveats. It is longer than average but each sentence adds value (format differences, race warning, session requirement). No filler. The structure flows logically from what → when → watch out, which earns a 4.

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 there is no output schema, the description adequately summarizes the output (headings mapped to pages, page count, last-page fullness) and notes that fullness figures are LaTeX-only. It covers format differences, performance implications, and prerequisites. While it doesn't detail the exact structure of the map, it provides enough for an agent to anticipate the result shape and call 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?

The schema already provides 100% description coverage for both parameters, including type, examples, and guidance for the project_id (remote vs. local, when to use). The description adds minor context like 'Omit file to use the compile root' (already in schema) and cost differences, but it does not add meaningfully to the parameters themselves. Baseline 3 is appropriate when 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 clearly states the tool maps every heading to the PDF page it starts on, plus total page count and last-page fullness. This is a specific verb+resource with a concrete output. It distinguishes itself from siblings like get_sections (which lists sections) and get_page_count (which just gives count) by specifying the mapping and positional nature of the output.

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 explicitly gives usage contexts: 'ideal for judging how content is distributed across pages and for a fill-exactly-N-pages workflow.' It also warns about cost differences between LaTeX and Typst and mentions a race condition risk, giving the agent criteria to decide whether to call it. However, it does not explicitly name alternatives or conditions to prefer another tool, so it lacks direct when-not 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?

The description discloses the conditional behavior of Typleaf's CLSI (only builds a Typst sync map when compiler is 'typst' AND root ends in .typ), which annotates the consequences of a wrong setting. It also calls out the session requirement. This adds meaningful context beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=true) without contradicting them.

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 every sentence earns its place: it front-loads the purpose, then explains the critical condition, the failure modes, and the requirement. While slightly long, the content is high-value and not padded, so it reads as efficient rather than verbose.

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

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

For a simple two-parameter setter with an enum and no output schema, the description is complete: it explains the behavior, the failure consequences, and the session requirement. The only minor gap is not warning explicitly about the destructiveHint=true annotation, which could merit a caution, but the context provided is otherwise 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 coverage is 100%, with the project_id parameter already extensively documented (format, source, and the remote-vs-local clarification). The description adds semantic value to the compiler parameter by explaining the special role of the 'typst' value, but mostly relies on the schema baseline, which 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 ('Set the project's compiler') and immediately clarifies the most common value ('most often to ‘typst'') and what that accomplishes. It clearly distinguishes itself from build/compile tools by explaining the setting's role in making a project a Typst 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 gives a clear use context: set the compiler to 'typst' when the project should be a Typst project, and warns of the failure modes (TeX errors that never mention Typst, PDF-position tools silently returning nothing) when left on pdflatex. It mentions the TYPLEAF_SESSION requirement but does not explicitly name alternative tools or state when not to use it, leaving some inference to the agent.

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 annotations already declare readOnlyHint: true, so the agent knows this is a safe read operation. The description adds value by listing what the overview contains (format, file count, heading structure), but it does not disclose any further behavioral details such as return format, order, or potential errors. Given the annotation coverage, a 3 is appropriate — it adds context but no critical missing behavioral information.

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, tightly-worded sentence that front-loads the primary action ('Get a quick overview') and specifies exactly what will be returned. No wasted words, and it is easy to scan.

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-only tool with a single fully-documented parameter and no output schema, the description adequately conveys what the agent will receive. It mentions the three components of the overview, which is sufficient for an agent to know what to expect. It does not describe output format, but that is not critical for a quick summary tool given the annotation and schema richness.

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 description covers the project_id parameter 100% with detailed guidance including format, example, and when to use the tool. The description field itself does not mention parameters, so it adds no semantic value beyond the schema. With full schema coverage, the baseline of 3 is correct.

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

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

The description uses a specific verb ('Get a quick overview') with a clear resource (the project) and enumerates three concrete pieces of information (format, file count, heading structure). This is distinct from the sibling file-editing and compilation tools, so an agent can immediately understand the tool's role.

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 a use case (quick overview) but does not explicitly state when to use this tool versus alternatives like read_file or project_info. The parameter schema includes broader guidance for the tool family ('Only call these tools when the user explicitly asks to work with a Typleaf project...'), but that is not part of the description itself. Since the context is slightly implied, it earns a 3 — clear enough but lacking explicit 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 this is non-read-only, idempotent, and non-destructive. The description adds value by revealing the underlying git pull behavior, which implies fetching and merging remote changes into the local working copy. This is more informative than a bare 'sync' label and does not contradict the annotations.

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 tight sentence conveys the core operation and the underlying mechanism. The parenthetical '(git pull)' immediately disambiguates the tool's meaning. There is no wasted or redundant wording.

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 sync tool with annotations already covering idempotency and destructiveness, the description is nearly complete. It could mention potential merge conflicts or return behavior, but the git pull framing gives an agent enough context to invoke the tool appropriately.

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 project_id parameter is thoroughly documented in the schema, including format, source, and what it is NOT. The description itself contributes no parameter information, 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 names a specific verb ('Pull'), a specific resource ('Typleaf'), and clarifies the exact operation with '(git pull)'. This clearly distinguishes sync_project from siblings like download_source, upload_file, or write_files, which involve different remote/local data flows.

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 project_id parameter description explicitly states these tools are only for Typleaf projects, never for general local file I/O, and advises preferring standard read/grep tools when a local checkout exists. It does not name a particular sibling alternative for pulling changes, but the git pull framing makes the intended use obvious.

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?

Beyond annotations (destructiveHint=true), the description adds key behaviors: it commits and pushes immediately, preserves the heading line, and selects the parser from the file extension. This provides useful operational context without contradicting the annotations.

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 concise sentences with no filler. The core action, supported formats, and side effect are front-loaded, making it easy to parse quickly.

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 tool is complex (mutating, commits/pushes, multiple formats, 5 parameters), yet the description omits critical details: how section_title is matched (exact vs fuzzy, case sensitivity), the role of the optional commit_message, and error behavior on missing sections. No output schema exists, so more explanation is needed but 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?

With schema coverage at 40%, the description should illuminate the undocumented parameters (file_path, section_title, commit_message), but it does not. It only implies section_title via 'by title' and new_content via 'body', leaving these param semantics to the reader.

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 verb 'Update' and the resource 'a section's body', and specifies it works 'by title' and 'preserving its heading line'. This distinguishes it from general file editing tools like edit_file, though it doesn't explicitly name 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?

The description gives no guidance on when to choose this tool over siblings like edit_file, rewrite_file, or get_section_content. It mentions supported formats, but no context about the intended workflow 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 mutation (readOnlyHint=false) and destructiveness (destructiveHint=true). The description adds valuable behavior beyond those: it handles binary files that must not be UTF-8 decoded, and it commits and pushes immediately. This gives the agent important operational knowledge not captured in annotations. No contradiction with annotations.

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

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

Three sentences with no filler. The purpose and binary warning are front-loaded, followed by the commit/push side effect. Every sentence earns its place, and the core message is immediately clear.

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 upload tool with a full schema, the description covers the essential behavior (binary handling, immediate commit/push). It could mention return values or success indicators, but given no output schema, that is not strictly required. The description is sufficient for an agent to call this tool correctly in the intended context.

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

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

The schema provides full descriptions for all five parameters (100% coverage), so the description does not need to elaborate further. The description's mention of binary handling is relevant to the overall behavior but does not specifically clarify any parameter beyond what the schema already states. Baseline 3 is appropriate given the high schema 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 ('Upload') and resource ('local file into a Typleaf project'), and explicitly scopes it to binary/non-text assets (images, PDFs). This clearly distinguishes it from siblings like create_file or edit_file, which likely handle text. The phrase 'must not be UTF-8 decoded' further clarifies the tool's niche.

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 explicitly states when to use the tool ('Use this for images (PNG/JPG), PDFs, and other non-text assets'), which gives clear context. It does not explicitly say 'use create_file for text', but the binary emphasis implies the exclusion. The 'Commits and pushes immediately' note adds behavioral context that helps anticipate side effects. A bit more explicit guidance on when *not* to use it (e.g., for text files) would merit a 5.

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?

Beyond the readOnlyHint annotation, the description discloses 'ZERO LLM calls', the three output buckets and their meanings, that 'unverifiable' is 'reported separately and NEVER as fabrication', and that for Typst it also reports broken references. This is rich behavioral context that guides the agent's expectations and safety.

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?

While several sentences long, every clause earns its place by explaining a distinct behavioral aspect or parameter nuance. The main purpose is front-loaded, and the use-case guidance is at the end. No filler or redundancy.

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 output schema, the description fully specifies what the agent will receive (three buckets with meanings), the input details, and edge cases (no identifier, coverage gap, book, rate-limit). It also notes Typst-specific broken references. Everything needed to call and interpret the result is 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 already has 100% coverage, and the description greatly enriches both parameters: for bib_path it explains auto-discovery logic (#bibliography(...), otherwise every .bib); for project_id it clarifies what it is not (not a path, not '.', not a name/title), how to obtain it (list_projects or URL), and the remote vs. local context. This far exceeds the schema's basic descriptions.

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 opens with a clear, specific verb phrase 'Detect likely-hallucinated references' and specifies the resource ('the project's bibliography'), then details the exact behaviors (BibTeX/Hayagriva, DOI/arXiv check, three buckets). This is unambiguous and distinct from the listed siblings, which are file/compile/project operations.

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

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

Explicitly states when to use ('Use to sanity-check an AI-assisted draft before submission'), when not to (do not use for general local file I/O; prefer read/grep for local checkout), and how to obtain the project_id. Also instructs to call list_projects first when unsure, giving a clear decision tree.

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 only mark destructiveHint=true, but the description discloses the atomic all-or-nothing behavior, validation-before-write, rollback on failure, and the two edit modes (content vs old_string/new_string). This goes well beyond the annotations and describes exactly what happens on failure and how edits are resolved.

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 concise paragraphs that front-load the core purpose and then elaborate on behavior and modes. The language is efficient and free of fluff, though the second paragraph could be slightly more structured (e.g., bullet points for the modes), but overall it is appropriately sized.

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 complex multi-file atomic write tool with no output schema, the description covers all essential behavioral aspects: atomicity, pre-validation, rollback, and the parameter semantics for each edit type. It also contrasts with sibling tools, making it sufficient for an agent to call correctly without additional documentation.

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 explains the meaning of the two edit modes (full replacement vs surgical match) and that old_string must match exactly once, which is not fully clear from the schema alone. However, it does not discuss the commit_message parameter at all, and the project_id parameter is described in its own schema entry, not in the tool description, so some semantics are delegated 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 (apply) and resource (coordinated change across several files) and explicitly contrasts with edit_file/rewrite_file loops. The 'all-or-nothing' qualifier adds precision and differentiates it from simple file writes.

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?

Directly instructs when to use this tool ('instead of calling edit_file/rewrite_file in a loop whenever the edits belong together') and gives concrete examples (converting call sites, renaming symbols, updating templates). Also explains the pitfall of a loop (project left in inconsistent state), which makes the usage guidance actionable.

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