productive-mcp

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

With no annotations provided, the description carries full burden for behavioral disclosure. While it mentions partial updates ('Only provide fields you want to change'), it doesn't address critical behavioral aspects like whether this requires specific permissions, what happens to unchanged fields, whether changes are reversible, or any rate limits. For a mutation tool with zero annotation coverage, this leaves significant gaps.

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 efficiently structured with a clear purpose statement followed by parameter explanations. Every sentence adds value, though the formatting with 'Args:' and bullet-like parameter list could be slightly more polished. The information is front-loaded with the core action first.

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?

Given this is a mutation tool with no annotations but with an output schema (which handles return values), the description provides adequate basics but has gaps. It covers parameters well and indicates partial updates, but lacks behavioral context about permissions, side effects, or error conditions. The presence of an output schema elevates it from a 2, but it's not fully complete for a mutation operation.

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?

With 0% schema description coverage, the description fully compensates by providing clear semantic explanations for all 5 parameters. Each parameter gets specific guidance: entry_id is sourced from productive_list_time_entries, hours is 'New hours value', date specifies ISO format, note is 'New note text', and service_hint is 'New service name or id'. This adds substantial value beyond the bare schema.

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 clearly states the action ('Edit a time entry') and resource ('time entry'), making the purpose immediately understandable. It distinguishes from siblings like productive_delete_time_entry (deletion) and productive_log_time (creation), though it doesn't explicitly name alternatives. The 'Only provide fields you want to change' adds useful context about partial updates.

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 implies usage context through 'Only provide fields you want to change' and references productive_list_time_entries for obtaining entry_id, suggesting this tool should be used for modifying existing entries. However, it doesn't explicitly state when to use this versus alternatives like productive_log_time for new entries or provide clear exclusion criteria.

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