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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces this with 'without changing anything' and adds meaningful behavioral detail: no-target mode reports current frequencies, target mode returns solutions, and only enabled outputs can be solved. This goes beyond the annotations 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 compact and well-structured: a one-line identity, a clear mode split, an example, a pointer to the applying tool, and a constraint. Every sentence contributes useful information with no repetition or filler.

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

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

The description covers the core behaviors, the main parameter semantics, the read-only nature, the follow-up action, and a key constraint (only enabled outputs). The main gap is the undocumented 'max_results' parameter, but overall the tool is understandable and actionable as described.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain the 'targets' parameter with a concrete JSON example and the optionality via 'with no targets', but it leaves 'project', 'name', and 'max_results' semantically unexplained. Since multiple parameters are undocumented in both schema and description, compensation is incomplete.

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 tool as a PLL calculator and specifies its two modes: reporting current VCO/PLL/output frequencies when no targets are given, and returning counter/divider solutions when targets are provided. This distinguishes calc_pll from sibling tools like edit_interface and run_sta_tcl.

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 when to use the no-target vs target modes and directs the user to apply a solution via 'edit_interface op auto_calc_pll', naming an alternative for the follow-up action. It doesn't explicitly state when not to use this tool versus other PLL-related tools, but the context is clear.

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

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

The annotations already mark the tool as destructive (destructiveHint=true), and the description adds useful context by specifying that child processes are also stopped. This goes beyond the annotation by clarifying the scope of the destructive action, which is valuable for an agent deciding whether to invoke the tool.

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

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

The description is a single, tightly worded sentence that front-loads the primary action and the scope of the effect. There is no redundant information or filler.

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

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

For a simple one-parameter destructive tool with no output schema, the description covers the essential behavior: stopping the job and its child processes. It does not mention where to obtain the job_id, but the sibling tool list_jobs fills that gap naturally, so the definition is reasonably complete.

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

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

Schema description coverage is 0%, and the description does not explain the job_id parameter beyond the schema's field name. While the parameter is simple and its purpose is inferable from the tool's name and description, the description does not compensate for the lack of schema-level documentation.

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 ('Stop') and a clear resource ('a running job and its child processes'). It clearly distinguishes this tool from sibling tools like list_jobs, get_job_status, and run_sta_tcl, so an agent can immediately understand its 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 the tool should be used when a job is running and needs to be stopped, but it does not explicitly state when not to use it or mention alternatives such as list_jobs or get_job_status for finding the job_id. The usage context is clear enough but not fully articulated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by enumerating the types of design rule violations checked, but it does not explain what happens after the check, whether it launches a job, or how results are returned.

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

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

The description is a single, well-structured sentence that front-loads the action and resource before giving concrete examples. Every element earns its place, and the list of check categories remains concise despite its detail.

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 one parameter and read-only annotations, the description is reasonably complete, but it lacks information about the return value or how the DRC results are surfaced. Since there is no output schema, the agent is left to infer whether the tool returns a pass/fail status, a report, or writes results to a list.

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

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

The schema has 0% description coverage for the single required 'project' parameter, and the tool description does not mention or define it. While 'project' is somewhat self-explanatory, the description does not compensate for the schema gap by explaining its format, purpose, or relationship to the saved design.

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 tool as running an Interface Designer design check (DRC) on the saved design, with a specific verb and resource. It also lists concrete examples of what is checked, making the tool's purpose unambiguous and distinguishable from sibling tools like get_interface_design or edit_interface.

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 the check should be run on the saved design, providing a prerequisite, but it does not explicitly state when to use this tool versus alternatives such as run_flow, get_interface_design, or calc_pll. There is no mention of exclusions or when not to use it.

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

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

Annotations provide minimal safety hints (readOnlyHint=false, destructiveHint=false), so the description must carry behavioral detail. It explains that the .peri.xml file is not created by this tool but by edit_interface, and clarifies path handling for design_files and sdc_files. This adds meaningful context beyond the annotations, though it does not mention side effects like overwriting or directory creation requirements.

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

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

The description is compact and information-dense, front-loading the purpose and then systematically addressing parameters. The line breaks aid readability, though bullet points or a table could improve scannability. No redundant sentences are present.

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 tool's complexity (10 parameters, no output schema, no parameter descriptions in schema), the description covers most critical information: parameter semantics, path handling, and the edit_interface dependency. It does not specify error behaviors (e.g., existing project handling) or the exact return value, but these are secondary for a creation tool and not covered by annotations or schema.

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

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

With 0% schema description coverage, the description compensates thoroughly. It enumerates allowed values for family (Trion | Titanium | Topaz), gives device examples (Ti375N1156, Ti60F225, T20F256), timing_model examples (C4, C3, I4), and clarifies path relativity and version defaults (verilog_2k, sv_09, vhdl_2008, vhdl_93). This transforms otherwise opaque parameters into actionable inputs.

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

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

The description opens with a clear, specific action: 'Create a new Efinity project .xml.' It identifies the resource and verb unambiguously, distinguishing it from siblings like update_project, list_projects, or run_flow. The inclusion of parameter families and examples reinforces the tool's identity.

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 contextual workflow guidance by noting that the Interface Designer file is created by the first edit_interface call before a full compile. However, it does not explicitly state when to use this tool versus alternatives (e.g., 'use create_project for new projects, update_project for modifications'), 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?

Even with annotations present, the description adds substantial behavioral detail: operations run in order, failure means nothing is saved, design checks gate saving, allow_new_errors bypasses the gate, dry_run avoids persistence, a .bak is written before save, and missing .peri.xml files are auto-created. This goes far beyond the annotation hints and gives the agent a precise execution model.

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 long but information-dense: every sentence adds a necessary semantic detail such as atomicity, validation rules, backup behavior, or op-specific constraints. It is front-loaded with the core purpose and then structured cleanly by operation type.

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 mutation tool with no output schema and minimal schema annotations, this description covers everything an agent needs: execution order, failure atomicity, save conditions, dry-run behavior, backups, PLL rules, valid values, post-save flow, and a GUI conflict warning. Missing return-value details are not material for a tool whose side effects and outcome conditions are so thoroughly specified.

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

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

Schema description coverage is 0%, so the description carries the full parameter burden, and it succeeds. 'project', 'operations', 'dry_run', and 'allow_new_errors' are all explained, with the operations array documented operation-by-operation including modes, bus syntax, resource assignment, override behavior, and example objects.

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 and resource: 'Change the Interface Designer design (.peri.xml).' This clearly distinguishes the tool from sibling read/check tools like get_interface_design, check_interface, and export_interface_isf by framing it as the mutation entry point.

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 operational context, such as dry_run behavior, error-check gates, backup creation, and the GUI reload warning, but it never explicitly states when to choose this tool over alternatives like calc_pll or check_interface. Usage is implied rather than directly contrasted with siblings.

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 indicate readOnlyHint=false (write operation) and destructiveHint=false. The description adds valuable behavioral context: it defaults to a specific file name in the project folder and supports filtering via block_types/instances. This goes beyond the annotations, though it does not disclose details like file overwrite behavior or other side effects.

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

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

The description is a single, well-structured sentence that front-loads the purpose, then covers format, use cases, and parameters. It contains no filler and every clause contributes essential information, making it efficient for an agent 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 description covers the output format, default location, use cases, and filtering options, which is sufficient for an export tool. It lacks an explanation of the export_all_pins parameter, but given the tool's simplicity and the presence of annotations, the overall guidance is quite complete. A brief note on that parameter would elevate it to a 5.

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 description coverage at 0%, the description must compensate for missing parameter documentation. It explains that block_types/instances limit what is exported, and the default file name implies the role of isf_file. However, it does not explain export_all_pins and gives only partial meaning to the parameters. The description adds some value but does not fully compensate for the lack of schema 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 states a specific verb ('Export'), a resource ('Interface Designer settings'), and a target format ('.isf, Python commands that recreate the blocks'). It clearly distinguishes from sibling tools by linking to the complementary import operation (edit_interface op import_isf) and describing the output's use as a readable backup or for copying settings, leaving no ambiguity about 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 gives clear usage context: 'Useful as a readable backup, for diffs, or to copy settings to another project.' It also mentions the companion import tool, which implies a workflow. However, it does not explicitly state when not to use this tool or name direct alternatives for exporting settings, so it stops short of a full 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 already declare readOnlyHint=true and destructiveHint=false, so the description does not need to cover safety. It does add context about what the summary includes (e.g., whether sources changed, resource usage, timing), which is useful. However, it does not disclose any potential edge cases such as behavior when no build exists or whether the query is expensive. Given that annotations cover the safety profile, 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 sentence that front-loads the primary action ('Summarise the latest build') and then lists the elements covered. It is efficient and avoids redundancy, though it could be considered slightly packed with information. It earns a 4 for being concise and 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 a read-only summary tool with a single parameter and no output schema, the description provides a good overview of what the result will contain. It does not mention failure modes (e.g., no build found) or prerequisite states, but these are minor for a status query. The description is sufficient for an agent to understand what the tool does and what to expect.

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

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

The schema has only one parameter (project) and schema description coverage is 0%, so the description must compensate by explaining what the parameter means. The description never mentions 'project' or indicates that the parameter identifies which project's build to summarize. The tool name and context make it inferable, but the description adds no semantic value for the parameter.

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

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

The description clearly states the tool's purpose: 'Summarise the latest build' and lists the specific elements it covers (outputs, timestamps, source changes, resource usage, timing, error/warning counts). It is specific about the resource (build) and the action (summarise). It does not explicitly name a sibling to differentiate from, but the content makes it distinct from detailed tools like get_utilization or get_timing_summary.

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

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

The description implies usage (when you want a summary of the build), but it does not provide explicit guidance on when to use this tool versus more detailed alternatives like get_timing_summary, get_utilization, or get_messages. No exclusions or alternatives are mentioned, so an agent must infer that this is the 'overview' tool.

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 provide readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description reinforces that this is a read-only informational call and adds specifics about what is returned, but does not go beyond the annotations with additional behavioral detail like latency, authentication, or format.

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

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

A single, front-loaded sentence that immediately states the tool's purpose and lists the exact information items. No filler or redundancy; every word contributes.

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

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

For a zero-parameter, read-only informational tool with a simple enumerated return list and no output schema, the description fully equips an agent to call it correctly. No prerequisites, side effects, or complex behaviors need explanation.

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

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

The tool takes no parameters, and the schema reflects that with 100% coverage. The description has nothing to add about parameter meaning because there are none, so 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?

The description states a specific verb ('Show') and resource ('the Efinity install this server uses') and enumerates the exact information returned: path, version, user settings folder, recent projects. It is unambiguous and clearly distinct from sibling tools, none of which cover this scope.

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 clearly implies when to use the tool: when the agent needs information about the server's Efinity installation. However, it does not explicitly discuss alternatives or conditions where another tool would be more appropriate, though no sibling appears directly comparable.

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 indicate readOnlyHint=true and destructiveHint=false, but the description adds behavioral context beyond that: it discloses the nature of the returned data (properties with allowed values) and special handling for PLLs (added calculated frequencies). This enriches the agent's understanding of what to expect from the tool 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 sentences with zero filler. The first sentence immediately states the tool's purpose and the format of returned values; the second adds a specific PLL enhancement. It is front-loaded with the most important information and uses precise terminology.

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 tool's purpose and usage context well, but it fails to explain the parameters, especially block_type, which is optional and ambiguous. Since there is no output schema, the description should clarify what the agent needs to provide and what the response structure looks like. The absence of parameter guidance makes it incomplete for a 3-parameter 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?

With schema description coverage at 0%, the description carries the full burden for parameter explanation, but it does not mention any parameter names or their roles. The optional block_type parameter is entirely unexplained, and even name and project are not explicitly described. The description only refers to 'one Interface Designer instance' without connecting it to the parameters.

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's function: retrieving all properties of one Interface Designer instance, including allowed value formats (choice lists, ranges, free-form). It also adds specific detail about PLLs (calculated VCO/output frequencies and reference clock source). This distinguishes it from siblings like get_interface_design or calc_pll by its focus on property enumeration.

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 recommends using this tool before edit_interface to obtain exact property names, which is a clear usage directive. However, it does not mention when not to use it or alternative tools like check_interface or calc_pll, so exclusions are missing.

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 (readOnlyHint=true, destructiveHint=false), the description adds valuable behavioral context: it reads from the saved .peri.xml file and explains the timing implication (GUI must save first). It also notes that include_check runs the design check, which is a non-mutating side effect. This adds meaningful transparency.

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 concise paragraphs, front-loading the core purpose and contents. The second paragraph efficiently covers parameters and behavior. No redundant sentences or fluff; it earns its length.

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 tool with three parameters and no output schema, the description is complete enough: it lists what is returned, explains filtering and the check option, and clarifies the data source. It does not describe the exact return format, but that's not essential given the enumerated contents and no output schema requirement.

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 0% schema description coverage, the description must compensate. It explains block_types with concrete examples (e.g. ['GPIO'] or ['PLL']) and clarifies include_check's purpose. project is self-evident. This adequately covers the parameter semantics beyond the raw schema.

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

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

The description clearly states it provides an overview of the project's Interface Designer design, enumerating specific contents (GPIO details, other blocks, I/O bank voltages). It is distinct from siblings like get_interface_block, though it doesn't explicitly name the alternative. The verb 'get' and resource 'Interface Designer design' are implied but clear.

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

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

The description gives usage context (reads saved file, so reflects GUI only after save) and explains the block_types filter. However, it does not explicitly mention when to use this tool versus alternatives like get_interface_block or check_interface, nor when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds meaningful context beyond this by explaining the effect of the include_core_interface parameter—that it adds the core<->periphery signal list—which is valuable behavioral information not captured in 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 exactly two sentences with no wasted words. The core purpose is front-loaded in the first sentence, and the parameter-specific behavior is isolated in the second. It is efficiently structured and easy to parse at a glance.

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 getter with two parameters and no output schema, this description covers the essential details: what data is returned, its source, and the behavior of the optional parameter. It lacks only minor details like return format or pagination, but these are not critical given the tool's simplicity and the annotations covering safety.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It explains include_core_interface's effect clearly, but it does not expand on the project parameter beyond what its simple name implies. The description partially compensates for the lack of schema documentation but not fully.

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 retrieves package pin assignments for user signals, listing the specific attributes (pin, bank, voltage, I/O standard, pull) and sources them from the Interface Designer pinout. While it distinguishes itself from interface design/block tools by focusing on pin assignments, it does not explicitly name sibling alternatives, so it stops short of a perfect 5.

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

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

The description implies its use when needing pin assignment data from the Interface Designer, but it does not provide explicit guidance on when to choose this tool over related siblings like get_interface_design or get_interface_block. No exclusions or alternative conditions are stated, so the guidance is implicit rather than direct.

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

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

Annotations already declare the tool read-only and non-destructive. The description adds useful behavioral context by disclosing the optional blocking wait (wait_seconds) and the response contents (stage results and last console lines). It does not mention timeout or failure behavior, but the safety profile is already covered by 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 three short, information-dense sentences with the core operation front-loaded. Every sentence earns its place, and there is no filler or redundant restating of the tool name.

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

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

For a read-only status-polling tool, the description covers the operation, optional wait behavior, and response contents despite having no output schema. It does not cover error handling or job_id format, but those are minor gaps given the tool's simplicity and helpful annotations.

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

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

The schema has zero description coverage, so the description must compensate. It explains wait_seconds ('wait up to wait_seconds for it to finish') and implies tail_lines through 'last console lines', but job_id is left entirely implicit and no parameter constraints, units, or formats are given. This is partial but not complete compensation.

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 operation as retrieving the status of a background job, and it specifies the job types ('flow run or programming'). It is distinct from list_jobs and get_build_status by resource, but it does not explicitly name or contrast itself with a sibling tool, so it stops short of 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?

The description gives no explicit guidance on when to use this tool versus alternatives like list_jobs, get_build_status, or cancel_job. The mention of 'optionally wait' implies a polling use case, but there is no stated condition for choosing this tool over related job-management tools.

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 and non-destructive, so the description adds value by explaining severity ordering, severity threshold behavior, and case-insensitive regex filtering. It does not mention output format or pagination, but for a read-only query tool this is a minor gap.

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

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

Two tight sentences deliver the core purpose first and then parameter semantics. There is no filler, repetition, or unnecessary detail.

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 filtered-list tool, the description covers the main resource, sort order, and filter semantics, while the schema supplies required parameters and defaults. It does not describe the output structure, but the return type is essentially named and no output schema exists.

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 0% schema description coverage, the description compensates by explaining the semantics of severity and pattern. However, it leaves project and limit undocumented, so it only partially covers the four parameters and relies on schema titles/defaults for the rest.

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 a specific resource: errors and warnings from the latest run of each named stage (synthesis, debug core, place, route, bitstream), and adds sort order. It is clear and specific, but it does not explicitly distinguish itself from sibling reporting tools such as get_build_status or list_reports.

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 scope and filter semantics imply when the tool is useful, but there is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives. An agent must infer its role among many reporting siblings.

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 and destructiveHint=false, and the description's "Read" aligns with them. It adds useful context about what is read (device, top module, files, flow options) but does not disclose output format, pagination, or other behavioral details.

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 filler. "Read a project's settings" states the operation immediately, and the following list of settings is compact and complete enough for orientation.

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, the description covers the operation and the settings domains. However, because there is no output schema, the agent is left uncertain about the result format, and the project parameter's accepted form is also unspecified.

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

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

Schema description coverage is 0%, and the description never directly explains the 'project' parameter or how it should be specified (name, path, ID, etc.). The phrase "a project's settings" only loosely connects the parameter to the operation without compensating for the missing schema 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 uses a clear verb and resource: "Read a project's settings," then enumerates the kinds of settings involved. It is not a tautology and is easily understood, though it does not explicitly contrast itself with related sibling tools like get_interface_design or get_timing_summary.

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 about when to choose this tool over alternatives, nor are there exclusions or prerequisites. The description only states what the tool does, leaving the agent to infer usage from 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 destructiveHint=false, covering the safety profile. The description adds behavioral detail by explaining what the tool returns ('worst critical paths... sorted by slack') and how parameters modify behavior (clock_filter filters by clock pair text, include_detail adds full cell/net breakdown). This goes beyond annotations to describe the output characteristics, though it stops short of specifying return format or pagination—acceptable given no output schema.

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

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

The description is two sentences: the first front-loads the core purpose and sorting behavior, the second explains the two filter/detail parameters and points to the alternative tool. Every sentence earns its place—no redundancy, no fluff. 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?

For a read-only reporting tool with annotations covering safety, the description provides sufficient information to call it correctly: what it does, how parameters affect results, and when to use the sibling tool. It doesn't describe the return format, but that's not critical since no output schema exists and the tool's purpose is clear. The only minor gap is that it doesn't explicitly state that project is required (though schema marks it required), and it doesn't mention the default for max_paths—both are minor.

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

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

With schema description coverage at 0%, the description must carry the meaning of parameters. It explicitly explains the two non-obvious parameters: clock_filter ('keeps paths whose launch vs capture clock pair contains the text') and include_detail ('adds the full cell/net breakdown'). It also implies that analysis is setup/hold via the enum and that max_paths controls count (inferred from name). While max_paths and project are not detailed, their meaning is self-evident. The description compensates well for the schema gap.

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 ('get') and resource ('worst critical paths') with a clear sorting criterion ('sorted by slack'). It explicitly distinguishes itself from the sibling tool run_sta_tcl by noting that custom queries should use that tool, preventing ambiguity. The purpose is unambiguous and immediately 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 explicitly tells the agent when NOT to use this tool: 'For custom queries (-from/-to/-through), use run_sta_tcl.' This is a clear exclusion and directs to the appropriate alternative. It also implies the typical use case: fetching worst paths with optional clock filtering and detail expansion. This level of guidance is rare and highly effective.

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 meaningful behavior beyond the readOnlyHint/destructiveHint annotations by stating that the data comes from <project>.timing.rpt and enumerating the metrics. It does not address edge cases like a missing report or whether timing is recomputed, but for a read-only summary the disclosure is solid.

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 one compact, information-dense sentence with the context front-loaded ('Post-route timing') followed by a precise list of returned metrics. There is no filler, repetition, or unnecessary restating of the tool name.

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

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

The description covers the source report, the returned metrics, and implicitly the read-only nature, which is reinforced by annotations. There is no output schema, but the enumerated fields give an agent enough to know what to expect; missing units or formatting details are minor.

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

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

With 0% schema description coverage, the description compensates by showing that project is used as the base name in <project>.timing.rpt, giving the single parameter concrete meaning. It does not explain project resolution or validation, but for one obvious string parameter this is adequate.

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 enumerates what the tool reports (constrained vs achievable frequencies, slack per clock pair, worst slack, timing met) and names the source report. It is unambiguous, though it lacks an explicit verb and does not explicitly distinguish itself from sibling tools like get_timing_paths.

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?

'Post-route timing' provides clear context about when the tool applies, and the summary content implies aggregate timing-status use. However, it never explicitly says when to choose this over get_timing_paths or run_sta_tcl, so the guidance remains implied rather than 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 mark the tool as read-only and non-destructive. The description adds useful behavioral context beyond the annotations by specifying the data stage (after place & route plus synthesis estimates) and the hierarchy=true behavior with total(self) values. No contradiction with annotations exists.

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

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

Two tight sentences front-load the output scope (core and periphery after P&R, synthesis estimates) before the optional hierarchy behavior. Every clause adds information and there is no filler or redundant restatement of the tool name.

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

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

The description is adequate for a simple read-only utilization query and covers output categories and hierarchy behavior. However, it omits the semantics of max_depth, any return format, and what 'synthesis estimates' means relative to the post-place-and-route numbers—gaps made more significant by the absence of an output schema.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains hierarchy=true and its breakdown semantics, and project is inferable from context, but max_depth is entirely unexplained—including how it relates to hierarchy—leaving an agent to guess its role.

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 tool as reporting resource utilization for a project, enumerating core resources (XLRs, memory, DSP, I/O, clocks), periphery, and synthesis estimates after place & route. It is specific enough to be distinguished from timing, job, and report siblings, though it lacks an explicit verb and does not name a differentiating sibling.

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

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

Usage is implied: call this tool when you need placed-and-routed utilization or synthesis estimates, and use hierarchy=true for a per-module breakdown. However, it provides no explicit guidance about when to prefer this over alternatives such as list_device_resources, or when not to use it.

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

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

Annotations declare readOnlyHint and destructiveHint, so the read-only nature is covered. The description adds valuable behavioral context by detailing what data is returned (package pin, I/O bank, features, alternate function, current user) and explaining free_only behavior, going beyond 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?

The description is information-dense yet well-structured: it leads with the purpose, then details GPIO and other block types, and ends with a note on free_only. Each sentence adds value without redundancy, though it could be slightly more compact.

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 listing tool with no output schema, the description covers the key aspects: what resources are listed, filter options, and the free_only toggle. It doesn't mention limit behavior or pagination, and the return format is implied but not explicit, leaving minor gaps.

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 0% schema coverage, the description must compensate. It explains bank, feature, block_type, and free_only with examples, but limit and project are left implicit. It partially covers the parameters but not all, missing explicit semantics for limit and project.

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 lists physical device resources for Interface Designer placement, with specific details about GPIO and other block types. It effectively conveys the resource type and scope, though it doesn't explicitly contrast with similar sibling tools like get_io_assignments.

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 filter usage guidance (e.g., bank, feature, free_only) but doesn't advise when to use this tool over alternatives like get_io_assignments or get_utilization. It implies usage through content but lacks explicit exclusions or selection criteria.

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

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

Annotations already establish that the tool is read-only and non-destructive. The description adds useful behavioral detail by scoping results to the server session and disclosing the newest-first ordering, which goes beyond what the annotations alone provide.

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

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

A single compact sentence that front-loads the action and packs the important scope and ordering information into the rest. Every word earns its place, with no filler.

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

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

For a zero-parameter, read-only list operation with an output schema, the description is complete: it states the scope, ordering, and what is being listed. The annotations and output schema cover safety and return shape.

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

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

The tool has zero parameters, so the baseline is 4; there is no parameter semantics for the description to clarify. The description appropriately avoids inventing parameter details.

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 ('List') with a clear resource ('jobs') and further narrows it to jobs started in the current server session, sorted newest first. This scope and ordering distinguish it clearly from siblings like get_job_status and cancel_job.

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 provides clear context for when the tool is appropriate: enumerating jobs in the current server session in reverse chronological order. It does not explicitly point to alternatives such as get_job_status for querying a single job, so it stops short of full explicit routing.

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 openWorldHint=true, covering the safety profile. The description adds context about what is detected (cables, dev boards, FPGAs on JTAG chain) but does not mention timeout behavior or potential hardware access requirements, which could be relevant. It adds some value beyond annotations but not extensive.

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, efficient sentence with no redundancy. It is front-loaded with the core purpose and avoids any filler, making it highly concise.

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 detection tool with one optional parameter and annotations covering safety, the description is largely complete. It does not specify the return format (e.g., list of cables and FPGAs), but this is often implicit for detection tools. The lack of output schema and low complexity make it acceptable.

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 single parameter timeout_seconds has a default but no description in the schema (0% coverage). The description does not mention this parameter at all, so it fails to compensate for the low schema coverage. The parameter name is self-explanatory, but the description adds no value to understanding its 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 uses a specific verb 'detect' and clearly identifies the resource: connected Efinix programming cables/dev boards (FTDI) and the FPGAs on their JTAG chain. This distinguishes it from sibling tools like program_device, which programs rather than lists, and other list tools.

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

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

The purpose implies usage before programming, but there is no explicit guidance on when to use this tool versus alternatives like program_device or other list tools. No when-not or alternative routing is provided, leaving the agent to infer the context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral detail by explaining that results combine GUI recent projects with filesystem-sourced projects and that output includes device and bitstream build time. This goes beyond the annotations 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?

Two sentences with no filler. The core action is stated first, the scope is defined precisely, and the optional parameter is woven in naturally. Every word contributes meaning.

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 listing tool with one optional parameter and an output schema present, the description is complete enough for an agent to select and invoke it correctly. It explains what is listed, where results come from, and what fields are shown, without needing to reproduce return-value details already available in the output schema.

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

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

Schema description coverage is 0%, so the description must carry the parameter meaning. It does mention search_dir inline as an alternative to the default project folder, giving some semantic value. However, it does not fully explain how search_dir is interpreted, such as whether it replaces the default folder, how paths are resolved, or whether search is recursive.

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

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

The description uses a specific verb and resource: 'List Efinity projects', and goes on to define the exact scope: the GUI's recent projects plus projects under the default folder or search_dir. It also states what information is returned (device, last bitstream build time), which clearly distinguishes it from sibling tools like list_jobs or list_reports.

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 clear context on what the tool covers, including the optional search_dir override, so an agent can tell when listing projects is appropriate. It does not explicitly name alternatives or state when not to use it, but the scope is sufficiently clear without exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the scoping detail that listing happens in the project's outflow folder, but it does not disclose other behavioral traits like recursion, sorting, or access requirements. This is acceptable, though not rich.

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, efficient sentence that front-loads the action and object. There is no filler or redundant information; every word contributes to understanding the tool's purpose.

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 only one required parameter, a direct description, annotations covering side-effect safety, and an output schema present, the tool is sufficiently documented for an agent to invoke it correctly. No additional details about return format or filtering are needed for this simple listing 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 schema has only one parameter, 'project', with no description and 0% schema description coverage. The description clarifies that 'project' refers to the project whose outflow folder will be listed. It does not specify whether the value is an ID, name, or path, but for a single simple string parameter this is minimally sufficient.

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 ('List') and a specific resource ('report and log files in the project's outflow folder'). This clearly distinguishes it from siblings like read_report, which would read file contents rather than enumerate 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 description clearly implies when to use the tool: when an agent needs to enumerate report/log files in a project's outflow folder. However, it does not explicitly mention when not to use it or name alternatives such as read_report for file contents, so the usage guidance is adequate but not fully 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?

The description goes beyond destructiveHint/openWorldHint by explaining exactly which modes are volatile ('lost at power-off') versus persistent and destructive ('overwrite what the board boots from'). This is concrete, decision-relevant behavior that annotations alone do not 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?

Bullet-style mode lines front-load the core semantics, and every sentence adds operational value. No filler or repetition.

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

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

For a 9-parameter, destructive, no-output-schema tool, the description covers the important decision points and warnings. The only notable gap is not describing what the call returns or how wait_seconds/verify_method affect execution, but the core usage is 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?

With 0% schema coverage, the description compensates well by explaining all mode variants, the project/file mutual exclusion, cable-selection parameters, and chain_device_number. It does not fully explain wait_seconds, jtag_clock_hz, or verify_method, so it is helpful but not exhaustive.

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 first line names a specific verb ('Program'), resource ('Efinix FPGA'), and mechanism ('Efinity command-line programmer'). The mode breakdown further differentiates it from sibling management/query tools such as list_programmer_cables or run_flow.

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 clear mode-selection guidance (JTAG vs flash vs bridge), instructs when to confirm with the user, and points to list_programmer_cables for cable selection. It stops short of explicitly stating which sibling tools should be used instead for non-programming workflow steps, but the context is strong.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful behavioral detail: section omission returns a sections list, pattern is a regex that returns only matching lines with context_lines, and offset/max_lines enable paging. This goes beyond the annotations 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 compact and front-loaded, starting with the tool's purpose and examples before moving to parameter usage. Each sentence earns its place; there is no filler or redundant restating of the schema.

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

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

The description covers the main parameters and provides useful tips, but with no output schema and seven parameters, it leaves some gaps: no guidance on choosing read_report over sibling tools, no mention of how to list available reports, and no explicit description of the return value except that matching lines and a section list are returned. It is adequate but not complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains section, pattern, context_lines, and offset/max_lines, and gives concrete examples for report. Only the project parameter is left to inference, but its meaning is fairly obvious from the required argument and tool context.

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 'Read any report or log' followed by concrete example filenames, clearly identifying the resource and action. This distinguishes read_report from listing tools like list_reports and from summary tools like get_timing_summary.

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

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

No explicit guidance is given on when to use this tool versus siblings. It does not mention that list_reports can be used to discover available reports, nor does it explain when get_messages or get_timing_summary would be more appropriate. The section hint about a returned 'sections' list is useful but is not a selection guideline.

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 async contract precisely: wait up to wait_seconds, return immediately if 0, return a pollable job_id if not finished, and include resource usage, timing, and errors on completion. It also notes the stage-flow dependency and that compile is the full path. This goes well beyond the sparse annotations (readOnlyHint/destructiveHint false).

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

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

Three short paragraphs front-load the core action, then clarify flow semantics and wait/poll behavior. Every sentence carries distinct information with no filler or repetition.

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

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

For a long-running async operation, the description covers the key return behavior (job_id vs final result), the flow enum semantics, and result contents. The main gap is the unmentioned timeout_minutes parameter and exact failure/timeout behavior, but the overall picture is sufficient for an agent to invoke it and know how to monitor the job.

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?

Flow and wait_seconds are explained in meaningful operational terms, and project is obvious as a required identifier. However, schema description coverage is 0% and timeout_minutes is never discussed, so the description only partially compensates for the missing parameter documentation.

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?

Description opens with an explicit verb and resource: 'Run the Efinity flow with efx_run.' It then defines what 'compile' means and the stage alternatives, distinguishing this from sibling run/build tools. The purpose is unmistakable and includes the domain-specific flow context.

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 tells the agent when to expect a full build vs a single stage, warns that stage runs require earlier stages to be current, and explains when a job_id is returned for polling with get_job_status. It stops short of explicitly listing when not to use run_flow relative to sibling tools like run_sta_tcl or program_device, so it is clear context without full exclusion 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?

Annotations declare readOnlyHint=true, destructiveHint=false, and the description adds important behavioral context: constraints set here only apply to this session and are not saved. It also specifies the design state (routed) as a prerequisite. This goes beyond the annotation's safety profile, though it does not mention execution time or output format. The description complements the annotations 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 front-loaded with the core purpose, then lists supported commands, and finishes with a note about session scope. It is slightly long but each sentence contributes useful information (scope, capabilities, help guidance, constraint persistence). The structure is logical and efficient, with no redundant filler.

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

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

The tool runs arbitrary Tcl and has no output schema, so the description should clarify what the tool returns (e.g., command output, exit status). It does not. It also omits prerequisites like the project being built and routed (though it mentions routed design) and error behavior. For a complex tool with no schema, more detail on expected results and failure modes would improve completeness.

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

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

Schema description coverage is 0%, so the description must compensate. It partially explains the 'script' parameter by listing supported SDC commands and pointing to help commands. However, it offers no guidance on the 'project' parameter (which project to target) or the 'timeout_seconds' parameter (its purpose, default, or consequences). This leaves some parameters underspecified, but the script parameter receives meaningful elaboration.

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 action: 'Run Tcl in Efinity's static timing analyzer on the routed design'. It distinguishes itself from sibling tools like get_timing_summary and get_timing_paths by positioning itself as the general-purpose Tcl interpreter that supports a wide range of SDC commands. The verb-resource pairing is precise and the scope is explicit, making the tool's role 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 implicitly conveys when to use this tool by listing the commands it supports (report_timing, check_timing, etc.) and noting that constraints are session-only. However, it does not explicitly state alternatives or exclusions (e.g., 'for simple timing queries use get_timing_summary instead'). It provides strong context about the tool's capabilities but lacks direct guidance on when not to use it.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds a useful non-obvious behavior: a .xml.bak backup is written first, which partially mitigates the destructive risk. It does not cover prerequisites or error behavior, but the backup note adds meaningful value beyond 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 sentences with zero fluff. The primary purpose is front-loaded, and the backup detail is a separate, valuable addition. 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?

The tool has 9 parameters and no output schema. The description covers the main edit actions but omits semantics for family and timing_model, and does not mention prerequisites (e.g., project must already exist) or how it interacts with create_project or run_flow. Given the complexity, more detail is needed.

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 0% schema description coverage, the description must compensate. It maps add_sdc/remove_sdc, add_files/remove_files, top_module, and device, but leaves family and timing_model unexplained. This is a partial compensation, not a complete one.

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 ('Edit') and resource ('project .xml'), and lists concrete operations: adding/removing HDL and SDC files, changing top module or device. This clearly distinguishes it from siblings like create_project and edit_interface.

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 the use case—modifying an existing project—but does not explicitly mention alternatives or when not to use this tool. Sibling names like create_project suggest the distinction, but the description relies on inference rather than explicit guidance.

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