get_area_analysis_result

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

Annotations already cover read-only, idempotent, and non-destructive, yet the description adds behavior they cannot express: results come from cache, no silent recomputation occurs, the resource_id is version-checked against the task's publication version, and expired results surface as TASK_RESULT_EXPIRED. That is the kind of failure-mode and staleness context an agent cannot infer from the schema or annotations.

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?

Labeled sections (Use when / Do not use when / Requires / Returns / Follow-up) front-load the routing decision and waste little space. The Returns line partially duplicates the already-present output schema, which is the only real 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?

For a paginated cache-read with an output schema, an agent has everything needed: precondition (task succeeded), parameter constraints, pagination path, staleness check, and the recovery action on expiry. No behavioral question is left open before invocation.

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 0%, so the description must carry the load: it states task_id must belong to a successful task and constrains page >= 1 and page_size >= 1, which the schema does not. It stops short of giving any bound or default rationale for page_size, leaving some semantics to inference.

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?

"Page a successful area task's existing cached result without recomputing" names a specific verb (page), a specific resource (a cached area-analysis result), and its defining constraint (cache-only, no recomputation). It is immediately distinguishable from siblings like get_area_analysis_task or submit_area_analysis.

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 when: get_area_analysis_task reports succeeded..." and "Do not use when: the task is queued/running and you only need to poll its state" give an explicit inclusion and exclusion with the alternative named. The follow-up line further routes to get_area_analysis_task for state and to resubmission on TASK_RESULT_EXPIRED.

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