anvil

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

Adds context beyond destructiveHint: describes mutation, default draft behavior, email sending, and test mode. Does not contradict annotations.

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?

Three efficient sentences: purpose, critical default behavior, and test mode advice. Front-loaded with important warnings.

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?

Covers creation, email side effects, and test/non-test usage. Missing description of return value (no output schema) but otherwise complete for a create tool with 8 params.

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 baseline is 3. Description adds minimal extra meaning beyond schema, e.g., 'passed straight through to Anvil' for files and signers.

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?

Clearly states it creates an Etch e-signature packet with documents and signers. Distinguishes from sibling tools like anvil_get_etch_packet (retrieve) and anvil_generate_etch_sign_url (generate URL).

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?

Explicitly warns about isDraft defaulting to true and that setting it to false sends emails. Recommends using isTest=true during development. Provides context for safe usage.

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

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

Annotations already declare readOnlyHint=true, and the description adds the list of returned fields and the GraphQL query name. This provides additional context beyond the annotations, such as the purpose for discovering org identifiers.

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 three sentences, front-loaded with the main action, and includes a usage hint and technical note (GraphQL query). Every sentence adds value with no wasted words.

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 zero parameters and a simple read operation, the description fully explains what is returned (user and organizations with specific fields) and its purpose. The sibling tools are clearly different, and no output schema is needed as the description details the return shape.

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?

There are no parameters, and schema description coverage is 100% (trivially). The description does not need to add parameter semantics; it implicitly confirms no parameters are required. Baseline score of 4 applies.

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 clearly states the tool gets the authenticated user and their organizations with specific fields (eid, name, slug). It distinguishes from sibling tools by noting it's a good first call for discovering org slugs/eids.

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 says 'Good first call to discover org slugs/eids for other tools,' providing clear usage context. It implies it's a read-only, no-parameter call but does not explicitly mention when not to use it or alternatives.

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

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

The description implies a read operation ('returns the finished PDF'), while the annotation destructiveHint: true indicates mutation. This contradiction undermines transparency. No additional behavioral context (e.g., side effects, permissions) is provided beyond annotations.

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?

Three sentences covering purpose, REST endpoint, and data key meaning. Front-loaded and free of unnecessary words 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?

Explains return format (filename, byteLength, pdfBase64) and the `data` parameter's role. Lacks details on error behavior (e.g., invalid cast_eid) but sufficient given high schema coverage and no output schema.

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 100%, so the schema already documents all parameters. The description reinforces the `data` object's role but adds minimal new meaning. Baseline 3 reflects adequate but not exceptional contribution.

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?

Description clearly states the tool fills a PDF template with data and returns base64 PDF. It specifies the action, resource (cast/template), and output format. However, it does not explicitly differentiate from sibling tools like anvil_generate_pdf, which could cause confusion.

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?

No guidance on when to use this tool versus alternatives. Sibling tools are listed but no usage context provided. Agent must infer from names and descriptions alone.

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

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

Annotations already mark destructiveHint=true; the description adds that it's a one-time URL and returns {url}, but does not elaborate on the destructive nature (e.g., URL expiry or side effects).

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?

Two sentences, front-loaded with the main purpose, no wasted words. Every sentence adds value: purpose, GraphQL mutation, return type.

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?

Description covers purpose, parameters, and return; given simplicity and annotation presence, it is mostly complete. Could mention that the URL is one-time use or has an expiration.

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% with clear descriptions; the tool description adds no additional semantics beyond the schema, which is adequate but not improved.

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 clearly states it generates a one-time embedded signing URL for a specific signer in an Etch packet, distinguishing it from sibling tools like anvil_create_etch_packet and anvil_get_etch_packet.

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 specifies the signing flow context (iframe/redirect) and implies use after creating a packet, but does not explicitly state when not to use or mention alternatives.

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

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

Annotations already include destructiveHint=true, indicating the tool may create a new resource. The description adds details on the return format and request structure but does not disclose additional behavioral traits like authentication needs or side effects. It neither contradicts nor significantly extends annotations.

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 concise and front-loaded: first sentence states the core purpose and output, followed by the REST endpoint, format-specific payloads, and return object. Every sentence adds value with no redundancy.

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 3 parameters, 100% schema coverage, and no output schema, the description is complete. It explains return values (filename, byteLength, pdfBase64), covers both input types, and provides examples. No output schema is needed thanks to the clear return format.

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 100%, so the schema already documents each parameter. The description provides concrete examples (e.g., data structures for html and markdown) that clarify usage beyond the schema, earning a score above baseline 3.

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 explicitly states it generates a brand-new PDF from HTML or Markdown, using a specific verb ('generate') and resource ('PDF'). It also distinguishes from sibling tools like anvil_fill_pdf by emphasizing 'brand-new', ensuring the agent can differentiate.

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 provides clear context on when to use this tool (generating new PDFs) and gives format-specific instructions. However, it does not explicitly state when not to use it or name alternatives, but the differentiation is implied.

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

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

Annotations already declare readOnlyHint=true. Description adds that it fetches specific fields and is used for filling PDFs, plus mentions the underlying GraphQL query. No contradictions.

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?

Two concise sentences. First explains what the tool does, second gives usage guidance and technical note. No redundant information.

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?

Covers purpose, usage, parameter, and output fields. Does not mention error handling or edge cases, but for a simple fetch tool this is sufficient.

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 has 100% coverage for the single 'eid' parameter. Description adds meaning by explaining that the eid is used to retrieve the cast and then as input for fill_pdf, providing context beyond 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?

Clearly states it fetches a cast (PDF template) by eid and returns title, version, and template status. Distinguishes from siblings by linking to anvil_fill_pdf and specifying it's for PDF templates.

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?

Provides clear context for using the tool: fetch cast, then use eid for anvil_fill_pdf. Does not explicitly state when not to use or alternatives, but the purpose is well-defined.

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

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

Annotations provide readOnlyHint=true, and the description reinforces this with 'Fetch' and 'check signature progress', avoiding contradictions. It adds details on what the response contains (status, details URL, signers), which is valuable beyond annotations.

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 two sentences with no waste. It front-loads the action and lists key outputs efficiently.

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 single-parameter, read-only tool with no output schema, the description provides clear purpose, usage context, and content of response, making it complete.

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% for the single parameter eid, which is described in the schema as 'The Etch packet eid (returned by anvil_create_etch_packet).' The description does not add further meaning, so baseline 3 is appropriate.

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 clearly states 'Fetch an Etch e-signature packet by eid' and lists the specific fields returned, differentiating it from sibling tools like anvil_create_etch_packet.

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 says 'Use this to check signature progress', providing clear context for when to use. It does not mention when not to use or alternatives, but the guidance is sufficient.

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

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

Annotations declare readOnlyHint=true, consistent with 'Fetch' verb. Description adds that it returns PDF templates and workflows and that it uses a GraphQL query, providing useful behavioral context beyond safety.

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?

Two sentences: first states purpose and return type, second gives usage. Front-loaded, zero wasted words.

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?

No output schema provided, but description hints at return content (organization, casts, welds) and mentions GraphQL query. Adequately complete for a read tool with two simple parameters.

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 already covers both parameters (100% coverage). Description adds crucial usage constraint (at least one required) and clarifies source of slug (from anvil_current_user), adding value beyond 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?

Uses specific verb 'Fetch' and resource 'Anvil organization and its PDF templates (casts) and workflows (welds)'. Clearly distinguishes from sibling tools like anvil_get_cast or anvil_get_weld which fetch individual items.

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?

Directly states requirement: 'Provide either its slug or its eid (at least one is required).' Provides hint on where slug comes from (anvil_current_user). Does not explicitly state when NOT to use, but context from sibling tools makes it clear.

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

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

Read-only operation (annotations confirm readOnlyHint). Description adds that it returns forges and mentions GraphQL query, providing useful context beyond annotations.

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?

Single concise sentence (22 words) that front-loads purpose and includes relevant details. No wasted text.

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 low complexity and complete schema coverage, description is sufficient. Explains return structure (forges) but omits error conditions or edge cases, which is acceptable for a simple read tool.

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?

Single parameter 'eid' is fully described in schema (100% coverage). Tool description does not add additional semantics beyond 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?

Clearly states 'Fetch a weld' with specific resource 'Anvil workflow' and includes what is returned (forges with fields). Distinguishes from sibling tools like anvil_get_weld_data by specifying inclusion of forges.

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?

Implied usage: when you need a weld by eid. No explicit guidance on when to use over anvil_get_weld_data or other siblings, nor when not to use.

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

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

Annotations already declare readOnlyHint=true, so the description adds value by specifying that it is a GraphQL query and listing the returned fields (completion state, test flag, creation time). It does not disclose error handling or auth needs but transparently describes the operation.

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 two sentences, front-loading the key information. Every word serves a purpose, including the technical note about GraphQL query. No redundant or vague text.

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 simple fetch tool with one parameter, no output schema, and read-only annotations, the description provides sufficient context. It explains what is returned and the mechanism (GraphQL query). Complete for the tool's complexity.

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% with a clear description for 'eid'. The description restates fetching by eid but adds no additional semantics such as format or example. Baseline 3 is appropriate as the schema already documents the parameter well.

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 clearly states the verb 'Fetch', the resource 'weldData record', and specifies it is 'a single submission to a weld (workflow)'. It lists the fields returned: completion state, test flag, and creation time. This distinguishes it from sibling tools like 'anvil_get_weld' which likely fetches the workflow itself.

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 does not provide any guidance on when to use this tool versus alternatives. It mentions fetching by eid but lacks explicit comparison with sibling tools like 'anvil_get_weld' or context for when this tool should be preferred.

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