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

No annotations are provided, so the description carries full behavioral burden. It discloses the conditional requirement that setting IGNORED allows an ignoreReason, and that agentTraceability records UPDATED Activity inline but requires both workflowId and workflowExecutionId for attachment — genuinely useful side-effect and prerequisite disclosure. However, it doesn't state whether this requires specific permissions, is reversible, or what happens if workflowExecutionId is missing (does it fail silently? partial update?). One step short of full transparency.

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?

Front-loaded with the core mutation, then enumerates statuses, then conditional guidance. Dense but each clause carries load. Slightly crowded with enum breadcrumbs and nested parentheticals, but no filler sentences.

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 15 params, 0% schema coverage, nested object schema, and no output schema, the description supplies essential context: the status enum meaning, the ignoreReason condition, and the workflowId/workflowExecutionId coupling for Activity attachment. It's incomplete on actorType/agentModel/cliVersion/skillVersion/policyVersion semantics but covers the high-stakes ones. Missing logical guidance for gitSha (likely paired with FIXED) and the purpose of the many agent-traceability params.

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. It documents the status enum semantics (WHEN to use each value) and the ignoreReason enum values and condition. It does not explain most of the 15 parameters — e.g., actorType, cliVersion, skillVersion, policyVersion, policyFile, userId, gitSha, branchName — but does explain the key conditional relationships (workflowId + workflowExecutionId pairing). Well above baseline given 15 undocumented params and 0% coverage.

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 (Update) and resource (TestChimp issue status) and clarifies the identifier format ('by ordinal id, same flexible issueId formats as get-issue-details'). It's readily distinguishable from siblings like 'get-issue-details' and 'create-issue' because it's the only status-mutation tool named. An agent knows exactly what this does without opening the schema.

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?

Explicitly documents when to use which status: set IN_PROGRESS_BUG after applying a code fix; set FIXED only after user confirmation / commits are pushed. It also routes to when ignoreReason applies (only when status is IGNORED). This is condition-specific, workflow-embedded guidance that goes well beyond the default.

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