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

Beyond the annotations (readOnlyHint=false, non-idempotent), the description discloses real behavioral facts: omitted questions are kept unanswered and a default is written, and the tool is limited to a Member, Admin or Owner. These are genuine side-effect and authorization details the annotations do not 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?

The front-loaded definition is dense with internal jargon and document codes (ONB-02.4, LEGAL-04.3) that consume space without helping the agent invoke the tool. The actionable content (answer format, defaults, who may call) is present but buried mid-paragraph.

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 single-parameter write tool with no output schema, the description covers who may call it, how answers are shaped, what happens to unanswered questions, and what the call returns ('the next questions, or the state done once the profile is saved'). That is close to complete for correct invocation.

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 carry the load, and it does reasonably: it maps each answer to a 'key' (the question field), an 'option's key' (option field), or the person's 'own words' (words field). This gives the three undocumented sub-fields usable meaning, though the exact key syntax is not shown.

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 clear verb and resource: answer the pending interview questions that make up the 'contract positions' practice profile. It distinguishes the operation from 'read' by saying answers are written and defaults applied, but it never names the sibling start_the_contract_positions or read_the_contract_positions to route the agent explicitly.

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?

Usage is implied (answer the questions 'that wait', after the profile is started) rather than stated. The description explains answer formats and what happens to omitted questions but gives no explicit when-to-use or when-not-to-use versus the start/do-later/read siblings.

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