run_sta_tcl

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.