import_functional_tests

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

With no annotations provided, the description carries the full burden. It explicitly discloses 'Mutating (bulk)' and then details behavioral nuances: the platform verifies associations, returns rejected ones under 'rejected_mappings', and still imports unmapped tests when associations are missing or rejected. This goes well beyond a generic schema and gives the agent an accurate mental model of side effects and outcomes.

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 and safety profile ('Mutating (bulk)'), then flows naturally into usage details, association edge cases, and alternatives. Every sentence contributes distinct, non-redundant information, so no sentence feels wasted despite the description being longer than a one-liner.

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 purpose, bulk mutation, association verification, rejection handling, unmapped test behavior, and explicit alternatives. An output schema exists, so omitting return-value details is appropriate. The only noticeable gap is that 'server_version' remains unexplained, and the description does not clarify whether there is any idempotency or duplicate-handling behavior.

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 documents 'model_id' and 'tests_json' well, and the description adds meaningful context for 'tests_json' (existing tests, optional objective associations, rejected mappings, unmapped behavior). However, 'server_version' is required but undocumented in both the schema and the description, leaving the agent to guess what value to supply. The description compensates for the main payload but not for the complete parameter set.

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 'Register tests that already exist in your codebase against a model's functional objectives,' which clearly states the verb (register/import), resource (existing tests), and purpose (counting toward functional conformance). It also includes 'Mutating (bulk)' and explicitly contrasts with 'add_functional_test' for single hand-authored tests, distinguishing it from sibling 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 description tells the agent to scan the repo's test suite and pass existing tests, and it explicitly directs to the alternative 'add_functional_test' for single hand-authored tests. It also points to 'suggest_functional_test_mappings / associate_functional_test' for later association, providing clear when-to-use and when-to-use-alternative guidance.

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