upsert_schedule_e

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the upsert matching rule via `id`, which is genuinely useful. However, it does not say whether a replace overwrites the entire rental object (dropping unmentioned fields like expenses or QBI flags) or merges them, nor does it mention any required fields or preconditions – critical omissions for a write tool that can silently destroy data.

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?

A single front-loaded sentence with zero filler; the match-key clause is placed where it is needed. Nothing is redundant or padded.

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 not be explained. But with no annotations, a 0%-described nested schema, and a many-field rental object, the definition is thinner than the tool's complexity warrants: the replace-vs-merge semantics, the required `property_description`, and `tax_year` behavior are all left unstated.

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 adds real meaning for the `id` field by explaining it is the match key that selects add vs. replace, which the schema alone does not convey. It adds nothing for `tax_year` (default 2026) or the nested `rental` fields.

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 pair and resource: 'Add or replace a Schedule E rental property', which is concrete and distinguishable from sibling upserts by resource (Schedule C, W-2, K-1, 1099). It also names the match key `id`, telling the agent how the tool decides add vs. replace. It stops short of naming any sibling explicitly, so a 4 rather than a 5.

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?

'Add or replace ... (matched by `id`)' implies the usage condition: supply an `id` to overwrite an existing rental, omit it to create one. That is inferred rather than stated, and there is no guidance on when to prefer this over other input-mutation tools (e.g. update_other_inputs) or what to do if the property is not already on the return.

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