land_projects_active

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

No annotations are provided, so the description carries the full burden. It discloses that reference resolution may add one verified deed GET before the target GET, with a hard two-request limit. This is a valuable behavioral trait that an agent needs to know for cost/latency expectations. It also discloses that populated resolved results include all three plot identities and resolution freshness. It doesn't state whether the operation is read-only, but 'Get' and the absence of any mutation language imply a read. The two-request limit and the freshness disclosure go beyond a minimal description, though it could have explicitly said 'read-only' or 'no side effects'.

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?

Four sentences, each carrying distinct information: what is returned, the empty-result semantics, input constraints, and the reference-resolution behavior. The most important scoping information is front-loaded. No filler or repetition of schema details. The description is dense but not bloated.

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 two-parameter read tool with no output schema, the description covers the key operational facts: input selection, empty-result semantics, and the extra GET behavior. It doesn't describe the exact shape of the returned record, but without an output schema that would be useful. However, the description does mention that populated resolved results include all three plot identities and resolution freshness, which gives a partial picture. The main gap is the lack of a concrete return structure example, but the description is still quite complete for an agent to call it correctly.

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 description coverage is 0%, so the description must compensate. It does: it explains that plot_id can be numeric or display label, that deed_uid is the upstream UID, and that the original UID spelling is also accepted. It also clarifies that exactly one of the two parameters should be supplied, which is not encoded in the schema (both are optional in the schema). This adds real meaning beyond the raw schema. It doesn't give examples of display labels or UID formats, but the core semantics are covered.

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 a specific verb ('Get'), a specific resource ('the land project record the upstream reports as active'), and a specific scope ('for one deed uid'). It also distinguishes itself from siblings like land_projects_history and land_projects_count by focusing on the active project for a single deed. The phrase 'one deed uid' and the mention of plot_id/deed_uid inputs make the tool's purpose unmistakable.

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 gives explicit usage guidance: supply exactly one plot_id or deed_uid, and notes that the original UID spelling is also accepted. It also clarifies a key semantic: a deed with no active project is a successful answer with no record, not a failure. This prevents an agent from misinterpreting an empty result as an error. It doesn't name a specific alternative tool, but the sibling list includes land_projects_history and land_projects_count, and the description's focus on 'active for one deed' implicitly distinguishes it. The explicit input constraints and the no-record-is-success note are strong usage guidance.

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