create_agent_variable

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

Beyond the annotations, the description discloses important behavior: optional inputs send defaultValue, environment variables are stored in defaultValue and never shown to the model, env values are referenced as {{var:VARIABLE_ID}}, and responses mask env values. These details materially help an agent understand side effects and secret handling for a mutating tool.

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 purpose is front-loaded and the later sentences cover genuinely complex behavior around defaults and environment variables. The description is somewhat dense and long for a two-parameter tool, but each section adds operational value rather than repeating structured fields.

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 non-readonly create tool with no output schema and a largely undocumented nested object parameter, the description provides enough context to call it correctly in common cases, including secret handling and response masking. It does not cover permissions, error behavior, or full variable-type constraints, so a small gap remains.

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 variable parameter is a nested object with no property documentation, so the description carries most of the burden. It compensates well by listing typical fields such as key, type, defaultValue, description, in, required, isEnv, and isGlobal, and by explaining defaultValue and isEnv semantics. It still leaves agentId and some type/value constraints implicit, so it is not complete.

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: "Add a variable to a Convocore agent." This clearly distinguishes creation from sibling tools such as get_agent_variable, update_agent_variable, and delete_agent_variable. The additional field examples reinforce what is being created.

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 gives useful operational guidance for environment variables and secret handling, including a dashboard workflow for keeping secrets out of chat. However, it does not explicitly say when to use create_agent_variable versus update_agent_variable or other sibling tools, nor does it state prerequisites or exclusions. Usage is therefore implied rather than fully specified.

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