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

readOnlyHint=true and idempotentHint=true are consistent with a code-generation read. Beyond annotations it discloses real behavior: the returned submit_url must be hardcoded (not moved into .env/NEXT_PUBLIC_*), the public key is not a secret, files_url points at the project inbox and must never appear in a public snippet, and file inputs require multipart with uploads enabled. That is substantial context the annotations cannot convey.

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?

Front-loaded with purpose and the 'do not invent a submit URL' constraint, but the single dense paragraph packs in post-invocation integration rules (bracket suffixes, fetch arrays, multipart, inbox URLs, success UI, env-var policy) and repeats the [] suffix rule twice. For a two-parameter read tool this is over-stuffed and would benefit from splitting invocation-critical guidance from downstream implementation notes.

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?

With no output schema, the description carries the burden of describing what comes back (html/astro/next snippet, submit_url, files_url) and the constraints on using it safely. Nothing an agent needs to call this correctly, or to avoid the common failure of inventing a submit URL, appears to be missing.

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% and the enum for framework is already documented in-schema as html/astro/next flavors. The description adds only a light constraint that form_id must reference an existing form ('after the form exists'); the long multi-value/file-input text describes the returned snippet, not the two input parameters. Baseline 3 is appropriate when the schema does the lifting.

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?

States a specific verb+resource: returns copy-paste html/astro/next code that posts to /s/:publicKey. That output is unlike anything any sibling produces (all siblings are CRUD on clients/forms/projects/submissions), so an agent can route to it without opening the schema. The first sentence also names the precondition 'after the form exists', which further pins what it does.

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?

Explicit about when to use it ('Use after the form exists'), when to hand-write instead ('Snippets are single-value inputs; write checkbox groups and multi-selects yourself'), and prerequisites ('Enable uploads on the project first'). It also covers what to do after receiving the snippet (add success UI, don't leave visitors looking at JSON) and routes to furrow://docs/submit-success and furrow://docs/testing for depth.

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