Add Functional Test

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the operation is mutating, that it records only the status the caller claims, that it does not run or verify anything, that CI verification happens separately, and that manually-added tests survive regeneration/refresh.

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?

Every sentence earns its place: purpose, mutation flag, routing to alternatives, and the no-verification caveat. It is dense but not bloated, and the most important information is front-loaded.

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 plus the rich schema cover purpose, alternatives, side effects, and the existence of an output schema means return values need no explanation. The only gap is that the required server_version parameter is undocumented in both the tool description and the input schema, which an agent may need to fill correctly.

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 high (83%), so the schema already documents most parameters; the description adds little parameter-specific meaning beyond reaffirming one-or-more objective mapping and the status-as-claim behavior. The required server_version parameter remains unexplained in both the description and 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 opens with a specific verb and resource: 'hand-author a single functional test and map it to one or more objectives.' It also names what the tool is not — generation and bulk import — which clearly distinguishes it from nearby siblings such as generate_functional_objectives and import_functional_tests.

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 explicit when-to-use guidance: use only to register an extra test that generation did not produce, use import_functional_tests for bulk-registering existing tests, and attach verification evidence via submit_functional_test_assertions. This leaves no ambiguity about when to choose this tool over alternatives.

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