alga_users_get

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds one useful behavioral nuance — that this returns 'full details' whereas list/search results are presumably summaries — but says nothing about not-found behavior, permissions, or visibility scoping.

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 short sentences, purpose front-loaded, usage hint second. Nothing is wasted and nothing is buried.

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 single-record read with annotations covering safety and no output schema to explain, this is close to sufficient. The only real gap is that 'full details' is left unquantified and the source of the ID is not stated.

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?

There is a single parameter and schema description coverage is 0%, so only the schema's pattern/minLength/maxLength constraints inform the agent. The description contributes only 'by ID', which confirms the parameter's role but adds no format, source, or example of where that ID comes from. Baseline 3 for a one-param tool.

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?

"Get one user profile by ID" names a specific verb (get), a specific resource (user profile), and a scope (single record, keyed by ID). That contrasts adequately with alga_users_list, though the description never names the list sibling explicitly, so the differentiation is inferred from 'one' rather than stated.

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?

"Use after a list or search to see full details" gives concrete sequencing guidance: this is a detail-fetch following a discovery call. It stops short of stating when NOT to use it (e.g., when the full record is already in hand from search) or what happens on an unknown ID.

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