upsert_schedule_c

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

No annotations are supplied, so the description carries the full behavioral burden. "Add or replace" does disclose mutation, but nothing is said about whether an omitted field is reset to its schema default on a matched replace (critical, since every field has a default such as gross_receipts=0), whether existing data is destroyed, or what permissions/validation apply.

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 tight sentence with the operation and matching key front-loaded and zero filler. Every clause maps to real content in the schema.

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 no explanation, but this is a large, deeply nested mutation payload with no annotations. The description covers the headline categories yet omits tax_year, ownership, QBI fields, and the consequences of replace-on-match, leaving an agent to discover those from the schema alone.

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% for the two top-level parameters, and several nested fields ship with empty descriptions, so the description must compensate. It does add the important `id`-matching semantics and maps four domain areas to schema fields, but leaves `tax_year`, `owner`, and the whole QBI/199A block unaddressed.

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 names a specific verb pair (add or replace), the resource (a Schedule C business), and enumerates the covered data domains: receipts, categorized expenses, home office, mileage. This clearly separates it from siblings such as upsert_schedule_e or upsert_1099. It stops short of an explicit sibling contrast, so it lands at 4 rather than 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?

"Matched by `id`" conveys the insert-vs-update trigger implicitly: supply an id to replace, omit it to add. Beyond that there is no guidance on when to prefer this over other upsert tools, no prerequisites, and no mention of what happens when an existing id is overwritten.

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