rightmove_agent_branch

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

With no annotations, the description carries the full burden. It discloses that the branch resolves by numeric id alone and that URL slugs are cosmetic, which is helpful. It also lists the return contents. However, it does not explicitly state whether the operation is read-only or any other behavioral constraints (e.g., authentication, rate limits), so it is adequate but not comprehensive.

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 two sentences, front-loaded with the primary action, and includes all necessary details without redundancy. Every clause adds value: the purpose, the return contents, and the id resolution note. This is appropriately sized and well structured.

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-parameter tool with no output schema, the description lists the specific return fields (address, telephones, service flags, affiliations, listing previews) and clarifies id usage. It is nearly complete, though it could explicitly state that it is a read-only operation, but given the simplicity, it covers what an agent needs to know.

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 describes the parameter as 'Rightmove agent branch id', but the description adds meaningful context by explaining that the slug segments are cosmetic and only the numeric id matters. This goes beyond the schema's minimal description and helps the agent correctly interpret and use the id parameter.

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 clearly states the action ('Get'), the resource ('Rightmove estate agent branch details'), and specifically notes it returns one branch profile with a list of included fields. It distinguishes from siblings like 'rightmove_agents' by emphasizing it returns a single branch, not a list. This is a specific and unambiguous purpose.

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 description implies when to use it (when you need a single branch's details and have a numeric id) but does not explicitly mention alternatives like 'rightmove_agents' or when not to use this tool. The context is clear enough for simple lookup, but there is no exclusion or comparison to siblings, leaving the agent to infer usage.

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