solidtime_goals

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds one behavioral fact not in the annotations: writes require confirmation (dry-run otherwise) and organization-scoped goals need an extension. It does not say what delete destroys, whether updates are partial or full replacements, or which actions are idempotent versus not.

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?

Three short sentences with no padding, and the writer-relevant constraints (extension requirement, confirmation requirement) are front-loaded. The style is telegraphic, which costs a little readability, and the action enumeration duplicates the schema enum, but overall it is efficient.

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?

This is a 13-parameter multiplexed CRUD tool marked destructive with no output schema and near-zero schema description coverage. A three-sentence definition covering only the extension and confirm requirements leaves an agent unable to construct a valid create/update payload or predict return values. Substantially more documentation is needed at this complexity.

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 only 15%, so the description must compensate and it largely does not. It touches only the confirm flag and the organization/team-goals extension; goal_id, target_seconds, period, comparison, week_start, timezone, member_id, is_archived and name are undocumented in both schema and description, leaving 13 parameters mostly opaque for a create/update call.

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?

"Time goals" names the resource and the action list (list/get/create/update/delete) implies full CRUD, so the general purpose is inferable. However the phrasing is a fragment rather than a stated verb+resource, and nothing explains what a goal actually is (a target_seconds threshold per period/member). The action list largely repeats the schema enum rather than adding clarity.

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?

"Organization goals need the team goals extension" and "Writes need confirm" give two concrete preconditions, which is genuinely useful routing information. There are no sibling goals tools to disambiguate against, and no explicit statement of when to pick list vs get or which actions count as writes. Usage is implied rather than spelled out.

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