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

Annotations already declare readOnly/destructive/openWorld, so the safety profile is covered. The description adds non-obvious behavior beyond that: a 25-result default cap and the fact that a shareable searchURL is returned alongside results — a side output an agent would not otherwise predict. It stops short of explaining how to page past 25 or what happens when filters conflict beyond the stated precedence.

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?

Five short sentences with zero filler, front-loaded with what the tool does before the constraint rules. Slight cost in terseness: 'mip' and 'listingIds' do not match the schema's minimumPrice/listing_ids, so a reader must translate.

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 an 18-parameter, no-output-schema search tool, the description covers purpose, key filter interactions, sort preconditions, and the return shape (up to 25 results plus searchURL). Gaps remain around undocumented simple params (beds, baths, zipcode as an integer, community_feature) and how to retrieve results beyond the default 25, but the essentials for a correct first call are present.

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?

With 67% schema coverage and 18 params, the schema does much of the work (sort enum, property_type, furnished, yearBuilt are documented). The description adds genuine value the schema lacks: filter precedence (zipcode beats community, listing_ids beats everything but sort) and the sort-dependent required companions. It leaves beds/baths/zipcode/community_feature semantics unexplained, and refers to 'listingIds'/'mip' rather than the actual parameter names listing_ids/minimumPrice.

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+resource+source: 'Search Florida listings through IDX Broker.' That clearly separates it from sibling tools like listing_details (single-listing lookup) or save_listings, though no sibling is named explicitly. The scope (Florida, IDX-fed) is concrete and unambiguous.

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 real operational routing rules: 'Provide community OR zipcode (zipcode overrides community)', 'listingIds overrides every filter except sort', and preconditions tying 'pra' to minimum price and 'sqfta' to sqft. It does not say when to choose this tool over listing_details or save_listings, so it stops short of full when/when-not guidance.

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