sql_check

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

With no annotations, the description carries the full behavioral burden and does well: it discloses that the Archery platform API is called, that the account must be whitelisted with deployment permission, and that when the platform is unavailable local results are retained with an explanation. What it does not disclose is how violations are reported or whether the check itself fails hard, leaving some behavioral ambiguity.

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?

Purpose is front-loaded in sentence one, the rule list is compact and scannable, and the Args section is separated cleanly. Every bullet carries information, though the formatting is denser than strictly necessary for a single-parameter 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?

For a tool of this complexity (local rule engine plus external platform dependency) the description covers scope, the external auth precondition, and degradation behavior, and an output schema exists so return values need not be explained. Only the failure/reporting semantics remain unstated, a minor gap.

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, and it does: 'sql: 待检查的上线 SQL，可包含多条语句（分号分隔）' tells the agent the value is deployment SQL and that multiple semicolon-separated statements are accepted. That is real semantic value (delimiter convention, multi-statement support) beyond the bare 'string' in the schema.

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

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

The opening line names a specific verb and resource ('检查上线 SQL' against built-in rules and Archery platform requirements), which is far more than a restatement of the name. It implicitly separates itself from the query-oriented siblings by stating that SELECT is not accepted. It never names those siblings to route the agent explicitly, so it stops short of a 5.

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

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

The enumeration of what is checked implies this is a pre-deployment validation step, but the description never states when to call it (e.g., before executing DDL/DML) or which sibling to use instead for SELECT queries. Usage is inferable from context rather than explicit, so it lands at minimum-viable.

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