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

Annotations only cover readOnly/idempotent/destructive flags; the description goes far beyond by disclosing cost (free for veterans), a rate limit (5/day), expected latency (5-8 minutes), async polling behavior, required write scope ('Allow running analyses'), and the exact error strings for read-only keys, rate limiting, and cross-user access. That is exactly the behavioral context annotations cannot carry.

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 verb and scope, and the sequencing, limits, and auth requirements are all load-bearing. The all-caps emphasis and the enumerated error-string catalog are slightly heavier than necessary, but nothing is truly wasted.

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?

With no output schema, the description does the right thing by explaining that results arrive via a later get_my_case_analysis call and how long to wait. The one small gap is what the immediate response returns (e.g. a job or run id) versus the eventual analysis payload.

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% and the single case_id property has no schema-level description, so the description must compensate — it defines case_id as 'the id of one of the veteran's own cases (from list_my_va_cases)', which supplies both meaning and provenance. It stops short of format details, but the ownership constraint is the operationally important part.

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?

States a specific verb and resource ('RUN the full VetAid analysis pipeline') and pins the scope to the veteran's OWN cases, explicitly on the veteran's behalf. This is clearly distinguishable from the sibling get_my_case_analysis, which the description identifies as the polling counterpart.

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?

Gives explicit when-to-use context (one of the veteran's own cases, sourced from list_my_va_cases) plus hard limits (5 agent-run analyses per day, no credits spent). It also names the follow-up tool and the condition that requires it: 'afterward poll get_my_case_analysis(case_id) for the results'.

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