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

Annotations declare readOnlyHint=false and openWorldHint=true but say nothing about lifespan or side effects; the description supplies the 7-day expiry, the fact that the actual listing creation happens in the browser with no login step, and the 401 failure mode. That is meaningful behavioral context beyond the structured hints, and it does not conflict with them.

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?

Front-loaded with the stage and purpose, then organized into numbered user steps, prefill rules, failure modes, and follow-ups — easy to scan. It is on the long side and the package index mapping is repeated verbatim from the schema, which is the only notable redundancy.

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?

An output schema exists, so return values need no prose, and the description covers everything else an agent needs: auth prerequisite, user-scoping, expiry, conditional parameter use, failure handling, and the exact next calls to make. Nothing required to invoke this correctly is missing.

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, and the description adds real value on top: it tells the agent when to include vs omit package, and warns that the value is a page preset index rather than a payPremiumOpt reference — a distinction that is easy to get wrong. It also reinforces list_address as the address already discussed in chat.

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 artifact — 'mint a pre-authorized link to the submit-property page' — plus the concrete endpoint POST /api/mls/submit-property-link. It explicitly positions itself against siblings by naming beycome_signin_verify as a prerequisite and beycome_get_my_listings / beycome_questionnaire_link as the follow-ups, and clarifies that this tool only returns a URL rather than creating the listing.

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?

Explicit ordering ('Call AFTER signing in'), explicit conditional parameter rules ('ALWAYS pass list_address', 'Only pass package if the user has clearly chosen a tier in chat; otherwise omit it'), a stated failure mode (401 — bad/unverified token), and a named post-return sequence. The description also states there is no in-chat alternative, which forecloses the agent looking for another tool.

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