agda_give

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

With no annotations, the description carries the burden of disclosure. It does state that Agda will check the expression and, if correct, replace the hole in the source file, which conveys a side-effecting operation. However, it omits error behavior when the expression is incorrect and does not mention any permissions or backup/recovery aspects.

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 well-structured and concise: a single-purpose opening line, a short behavioral clause, and a straightforward argument list. Every sentence contributes without redundancy, making it easy for an agent to parse quickly.

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?

The tool modifies source code and has a follow-up action (agda_load), but the description does not cover failure modes or the output schema (which exists). It is adequate for a simple tool but leaves gaps around what happens if the expression is invalid or if the goal_id is stale.

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 0%, so the description must compensate. It lists each parameter with a brief but meaningful explanation: file_path is an absolute path, goal_id comes from agda_load output, and expr is the expression to fill. This adds value over the bare schema, though it could be more detailed about expression syntax or valid goal_id ranges.

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: 'Fill a goal/hole with a complete solution.' This clearly distinguishes it from sibling tools like agda_refine or agda_intro, which perform different actions on goals. The mention of 'complete solution' further clarifies its purpose.

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 implies usage by stating 'Call agda_load afterwards to refresh goals,' which gives a workflow context. However, it does not explicitly state when to prefer this tool over alternatives like agda_elaborate_give or agda_refine, nor does it provide any exclusions or conditions.

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