land_projects_count

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

With no annotations provided, the description carries the full behavioral burden, and it delivers: it discloses this is 'one call,' that reference resolution 'may add one verified deed GET before the target GET' with 'a hard two-request limit,' and that populated resolved results 'include all three plot identities and resolution freshness.' It even surfaces a correctness caveat about count coverage. This is unusually rich disclosure for a count endpoint.

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 dense but front-loaded with the core purpose in the first sentence, then layers usage, behavioral, and caveat details in logical order. No sentence is wasted; even the verification caveat earns its place by warning the agent about potential mismatch with the history tool. It is longer than typical but every clause carries signal, so the length is justified.

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 count tool with two optional parameters and no output schema, the description is nearly complete. It states the return is 'the upstream's count only' and describes the resolved-result content. The one gap is the exact return shape—whether the count is a bare integer or wrapped in an object—which is not stated and no output schema exists to fill the gap.

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, and it does. It clarifies that plot_id accepts a numeric or display label, that deed_uid accepts the 'original UID spelling,' and that exactly one of the two must be supplied—an exclusivity constraint the schema itself does not express. It explains the reference-resolution side effect of a possible extra GET. Only the integer-versus-string nuance of plot_id is partially implicit rather than explicit.

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 opens with a specific verb-resource-scope statement: 'Get the count of land project records the upstream reports for one deed uid.' It explicitly distinguishes itself from the history sibling by stating it returns 'the upstream's count only, not the records' and even flags that the count's coverage versus the history tool 'has not been verified.' An agent can tell this apart from land_projects_history and land_projects_active without opening their schemas.

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 clear invocation guidance: 'Supply exactly one plot_id (numeric or display label) or deed_uid,' establishing the one-of parameter requirement and accepted input formats. It implicitly routes count-seeking agents here versus the history tool for record retrieval, though it never names an explicit alternative. The caveat that count coverage against the history tool is unverified is a useful when-to-trust signal.

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