vectis_save_report

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

With readOnlyHint=false, 'Save' correctly signals mutation, and the description adds that the call returns a report and provider cost ledger, which the annotations do not reveal. It does not discuss side effects like overwrites, idempotency, or cost implications, but it does not contradict the 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?

Two short sentences are front-loaded with the primary action and add one useful negative/return statement. It is not padded, though the phrase 'written by YOUR assistant' is slightly redundant given the tool name.

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 save operation with a large nested report object, no parameter docs, and no output schema, the description is too thin: it omits missionId semantics, required report content, and what the cost ledger actually represents. The return statement helps, but an agent would still need to infer most schema details.

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?

The schema has 0% description coverage, and the description only gestures at report content ('analysis', 'drafts', 'evidence', 'limitations') without defining missionId or the required report fields. This leaves an agent without enough information to construct a valid payload beyond what the raw JSON Schema already shows.

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 an exact action ('Save') and a specific resource ('analysis and drafts ... with evidence and limitations'), so an agent can tell this is a persistence step rather than an analysis or email tool. It does not name sibling tools directly, but the boundary statement 'Vectis does not analyze or send email' helps distinguish it from the search/email siblings.

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?

It establishes the correct context: use this for saving the assistant's already-written analysis and drafts, not for doing analysis or sending email. It does not explicitly name when-not-to-use alternatives or a sibling fallback, so it stops short of full routing guidance.

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