construct_netlogo_instrument

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered, yet the description still adds substantial behavior: where the recorder hooks in (after setup's reset-ticks, recording after go's tick), the fallback for models that never tick (record by steps), and the concrete return set (model, headless BehaviorSpace experiment, construct.nls). Adding the licence caveat for library models is useful context. It stops short of stating that nothing is written to disk, which would fully close the loop.

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 content is dense and mostly earns its place, but it is delivered as a single run-on paragraph heavy with parentheticals, which weakens front-loading. The leading clause 'A NetLogo 7 model (.nlogox text) that records its run' delays the operative point, and the trailing licence sentence is tangential to invocation.

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 an 11-parameter tool with nested objects and no output schema, the description covers the overall contract and output artifacts but leaves more than half the inputs unexplained. An agent could construct a basic call but would be guessing on reporters, turtles, seed and every. Given the complexity, it should do more to specify the recording configuration.

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 55%, so the schema documents roughly half the parameters and a baseline of 3 applies. The description does add meaning for go and setup (they default to the model's own buttons) and for ticks (the experiment's length), but seed, every, patches, turtles, reporters and skip_turtles get no explanation anywhere — the most complex nested parameters (patches.reporter, patches.every) are left entirely to the schema.

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 identifies the resource specifically (a NetLogo 7 .nlogox model that records its run for Construct) and implicitly the operation of instrumenting a supplied model with a recorder. It also names construct_netlogo_draw as the downstream step, which separates it from a sibling. The only gap is that the verb is never stated directly — it opens with 'A NetLogo 7 model...' rather than 'Instruments a model...' — so the agent must infer the action from the parameter list.

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 lays out a workflow — save the returned model, experiment and construct.nls beside each other, run in NetLogo, then draw run.jsonl with construct_netlogo_draw — which gives real context for what to do next. However, there is no explicit guidance on when to choose this tool over others or prerequisites such as needing the model's setup/go commands; usage is implied by the workflow rather than stated as selection criteria.

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