Set Profile

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

With no annotations provided, the description carries the full behavioral burden. It discloses the most critical behavior: 'Only the fields you pass are changed.' This clearly indicates a partial-update, non-destructive semantics. It also implies persistence by the verb 'Save'. It does not discuss error conditions or auth, but for a profile setter this is sufficient.

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 tightly written with every sentence earning its place: a direct purpose statement, a timing instruction, a rationale for several fields and a behavioral note. The most important behavioral detail is placed at the end, while the key 'who' and 'when' appear first. No fluff or repetition.

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 the tool has an output schema, return values are covered. The description provides the essential calling context: when to invoke (start), how to gather data (conversation, not interrogation), and update semantics (partial update). For an all-optional parameter set, this is complete enough for an agent to call correctly.

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 coverage is 100%, so the baseline is 3. The description adds beyond the schema by explaining the purpose and acquisition strategy for key parameters: 'School and graduation year make alumni outreach work. Background, goals and constraints are what let you judge fit properly instead of guessing.' This gives the agent context for how to value and fill these fields, which the bare schema descriptions lack.

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 opens with a specific verb and resource: 'Save who the user is.' It clearly identifies the tool's purpose as storing the user's profile information, which distinguishes it from all sibling tools. The added instruction 'Ask for this once, at the start' provides temporal context that pins down its role in the conversation flow.

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 explicitly states when to use the tool ('Ask for this once, at the start') and gives guidance on how to populate fields ('fill them in from what the user tells you in conversation, not by interrogating them'). However, it does not explicitly mention exclusions or alternatives among siblings, though none seem directly competitive. This is clear context without formal when-not guidance.

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