Справка по API Godot

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

Annotations already declare read-only, non-destructive, closed-world. The description adds that class structure comes from ClassDB and is accurate/current, and that search covers global project classes, which is useful context beyond annotations. But it does not disclose build_api_index behavior and misdescribes documentation as a mode rather than the include_docs flag.

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?

Single dense paragraph, front-loaded with the tool's purpose and then each mode. No filler; parenthetical details are compact. Slightly cluttered but efficient.

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

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

9 parameters with 56% schema coverage and no output schema. The description should document all modes and parameters but misses build_api_index, confuses modes with the include_docs flag, and leaves kinds/limit/sections unexplained. Too incomplete for a tool of this complexity.

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

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

Schema coverage is 56%. The description explains the mode parameter values but contains an error: mode=docs does not exist (include_docs boolean does), and build_api_index is never mentioned. Parameters kinds, limit, and sections remain undocumented in both places. Partial compensation only.

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

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

States it is a reference for engine classes and breaks down what each mode returns (methods/properties/signals for info, API-wide search, enum values, inheritance). Clear verb+resource, distinguishable from project-oriented siblings. However it references a nonexistent mode=docs and omits build_api_index, which slightly muddies the purpose for an agent.

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

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

Gives explicit mode-by-mode guidance: mode=info for class structure, mode=search for API queries, mode=props for enum values, mode=inheritors for inheritance. No explicit when-not or sibling comparisons, but mode dispatch is well covered. The missing build_api_index and spurious mode=docs reduce reliability.

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