Get Linked Endpoint Contract

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

Annotations only provide readOnlyHint=true. The description adds meaningful behavioral context beyond that: it returns null when the case is not linked, it requires project context, and it details exactly what the returned contract contains. This is strong disclosure for a read-only tool.

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?

Two compact sentences front-load the core object and its contents, then deliver the use case, null edge case, and context requirement. Every sentence earns its place and there is no filler or repetition of structured fields.

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?

Given one parameter, a read-only annotation, and no output schema, the description is complete enough: it explains what the returned contract contains, how to use it, what happens when there is no linked endpoint, and the project-context prerequisite. An agent has sufficient information to call and interpret the result 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?

The input schema already fully describes testCaseId as the public ID (GUID) of the test case, with 100% schema description coverage. The description reinforces the link between the test case and the endpoint contract but does not add meaningful parameter-level detail beyond what the schema provides.

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 names a precise verb and resource: 'Get the request contract of the spec endpoint a test case is linked to' and then enumerates the contract contents: header parameters, request body schema and example, and response schemas per status code. This clearly distinguishes it from generic endpoint, spec, and contract 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?

It explicitly states the intended use: 'use it to write assertions that match the contract instead of guessing.' It also frames the output as what the case is expected to send and receive. However, it does not name sibling tools or exclusion conditions, so it stops short of full routing guidance.

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