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

Annotations only declare the safety profile (readOnly=false, idempotent=false, destructive=false). The description goes well beyond by stating the effect on consumers ('the service's connection details are delivered for them'), the deployment prerequisite, the create-vs-update semantics, and the required permission scopes ('applications.deploy and clusters.operate'), which the agent cannot get from structured fields.

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?

Four sentences, front-loaded with the core action, each carrying distinct information (purpose, setup semantics, prerequisite, revision behavior, permissions). The CLI-twin parenthetical is the only element that does little work for an MCP agent.

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?

For a 6-parameter mutation with no output schema, the description covers prerequisites, side effects, create-vs-update behavior, and auth requirements. Remaining gaps are minor: no return-value guidance and no statement about what happens to an existing binding when expected_revision conflicts.

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 100%, so the baseline is 3. The description still adds workflow-level meaning to two parameters – allow_planned relaxes the deployment prerequisite, and expected_revision selects update-over-create – rather than just restating the schema's field descriptions.

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 a specific verb and resource with scope: 'Bind an application namespace on a cluster as a consumer of managed services.' An agent can distinguish it from list_service_consumers or unbind_service_consumer by the verb alone, though the description differentiates itself via a CLI twin ('ankra services consumers bind') rather than by naming the relevant 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?

Gives clear preconditions ('The application must be deployed to that namespace unless allow_planned is true') and create-vs-update routing ('Pass expected_revision to change an existing binding; omit it to create one'). It does not explicitly point to unbind_service_consumer as the way to remove a binding, so the alternatives story is incomplete.

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