Api applied controls todo retrieve

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

Annotations declare readOnlyHint=true, destructiveHint=false and idempotentHint=true, yet the description claims the endpoint allows applied controls to be "edited", directly contradicting the read-only annotation. It also discloses nothing about authentication, filtering, or the shape of the returned to-do list. Flagged as an Annotation Contradiction.

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?

It is a single short sentence, but brevity here is under-specification rather than concision: the sentence is front-loaded with a useless preamble ("API endpoint that allows...") and contains no tool-specific information.

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?

With no parameters, no output schema, and no informative annotations beyond safety hints, the description is the only source of meaning an agent has, and it omits what the endpoint returns and what "todo" means. An agent cannot confidently choose this over the many sibling applied_controls retrieval endpoints.

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 has zero parameters, so there is nothing for the description to expand on and the baseline is high. However, with no parameters the description carries the burden of explaining the endpoint's implicit scope (which applied controls count as "todo"), and it says nothing about it.

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 is generic Django-REST-Framework boilerplate: "API endpoint that allows applied controls to be viewed or edited." It never mentions the defining characteristic of this endpoint (the "todo" scope) and cannot be distinguished from the dozens of sibling tools such as applied_controls_retrieve, applied_controls_list, applied_controls_to_review_retrieve, or applied_controls_update.

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?

There is no when-to-use guidance at all: no mention of what a "todo" applied control is, when an agent should call this instead of applied_controls_list or applied_controls_to_review_retrieve, and no prerequisites. The only hint ("viewed or edited") is not actionable and arguably points the agent toward the wrong sibling.

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