agent_studio_get_agent_by_id_deprecated

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the deprecation note, which is a behavioral trait, but it provides no other behavioral context such as return format, authentication requirements, or any side effects. With annotations covering safety, the bar is lower, but the description still offers minimal additional transparency beyond the deprecation status.

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?

The description is extremely short, which could be seen as concise in length, but it is under-specified rather than efficiently structured. It provides no elaboration that would help an agent use the tool. The single phrase could have been expanded with useful details without becoming verbose, so it fails to make every sentence earn its place.

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 the tool has 3 parameters, no output schema, and is deprecated with a sibling non-deprecated version, the description is grossly incomplete. It says nothing about what the tool returns, when to use it, or how it relates to alternatives. An agent is left without essential guidance for correct invocation, making this definition inadequate even for a simple retrieval tool.

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 description mentions no parameters at all. Schema coverage is only 33%, with only locationId having a description ('Defaults to GHL_LOCATION_ID when omitted.'), while agentId (the required parameter) and source have no descriptions. The description does nothing to compensate for this low coverage, leaving the required parameter completely undocumented.

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 states 'Get Agent (Deprecated)' which conveys the basic action and resource, but it's minimal and does not go beyond the tool name. It does not specify that it retrieves by ID beyond the name itself, and it does not differentiate from the sibling 'agent_studio_get_agent_by_id' which appears to be the non-deprecated version. The description essentially restates the name with a deprecation tag, lacking specificity.

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?

The only usage hint is 'Deprecated', which implies it should be avoided, but it does not name the preferred alternative or provide any condition for when to use this tool versus the non-deprecated sibling. No explicit guidance is given on selection between this and 'agent_studio_get_agent_by_id' or when this might still be appropriate.

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