va_get_sync_status

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It doesn't disclose what a 'running', 'completed', or 'failed' status looks like, whether this is a read-only polling operation, whether it blocks, or what happens if the syncId is invalid or stale. For a status-checking tool, describing the return format would be valuable.

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 a single, efficient sentence with zero waste. It conveys the core purpose immediately and is well front-loaded. It's appropriately brief for a status-checking tool, though it could add a bit more behavioral detail without becoming verbose.

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 status-check tool with no annotations, no output schema, and 0% schema description coverage, the description is thin. It doesn't explain the possible status values, response format, timeout/retry expectations, or relationship to the sync-starting sibling tool. More context is needed for an agent to use this effectively in an async workflow.

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, but it only mentions 'sync job' conceptually. It doesn't clarify that kbId identifies the knowledge base and syncId identifies the specific job, though these are somewhat inferable from tool context. Both parameters are required and their names are reasonably self-explanatory despite being undocumented.

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 uses a specific verb ('check the status of') applied to a resource ('knowledge-base sync job'), and correctly notes this applies to a 'previously started' sync job, distinguishing it from the sibling va_sync_knowledge_base which initiates syncs. It clearly states what the tool does, though it doesn't explicitly contrast with the sibling that starts syncs.

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 phrase 'previously started' implies this is meant to be called after va_sync_knowledge_base, providing implicit usage context. However, there's no explicit when-to-use vs when-not-to-use guidance, no mention of alternatives, and no indication of polling behavior or whether it should be called repeatedly.

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