Signatoro

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

Annotations already declare write/non-destructive/non-idempotent/open-world, so the bar is lower. The description still adds real context: an invitation email is sent, the invitee receives their signature, the action consumes the plan's people limit, and it requires owner permissions. It doesn't clarify whether the invitation expires or what happens on duplicate email, but the added side-effect and auth detail is substantial.

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 short sentences, front-loaded with the action and its effect, then prerequisites and alternatives. No filler; every clause carries either behavior, constraint, or routing 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?

No output schema exists, so the description must carry the load, and it does: side effects, permission requirement, plan-limit impact, and sibling routing are all present. An agent has everything needed to call this correctly or route elsewhere.

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 3 is the baseline. The description goes slightly beyond the terse schema labels by explaining that name, title and phone feed 'their signature', giving the fields a purpose rather than restating them, and it clarifies email is the invitation channel.

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 and resource (invite/add a person to the company) plus the scope of data supplied. It explicitly names the siblings it is NOT, letting an agent separate it from update_member_field and resend_invite without opening any schema.

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?

Gives explicit when-not/alternative routing: 'For someone already in the company, use update_member_field; to send an invitation again, use resend_invite.' It also states the prerequisite 'Company owners only', so both selection and eligibility are covered.

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, idempotentHint and destructiveHint=false, but the description adds genuinely new behavioral context: nothing is persisted, no account is required, and the caller receives HTML, plain text, and an edit link. It does not describe rate limits or any failure modes, keeping it just short of a 5.

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, front-loaded with purpose and return format, then routing rules. Slightly redundant in re-enumerating eight fields that the schema already names, but nothing is padded or off-topic.

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 return-value burden and does so — HTML, plain text, and an edit link are all described. Combined with the explicit sibling routing, an agent has everything needed to call this correctly.

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 every parameter including the layout enum and hex color pattern is already documented in the schema. The description only re-lists the field names and adds no format, default, or constraint detail beyond the schema, so the baseline 3 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 opens with a specific verb+resource ("Make a free email signature") and enumerates the inputs, so there is no ambiguity about what it produces. It also names the two sibling tools it is not — update_my_signature and get_signature — letting an agent distinguish it without reading schemas.

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 routing is provided: saving to an account routes to update_my_signature, retrieving an already-saved signature routes to get_signature. The condition that selects each alternative is stated verbatim with example user phrasings ("create my signature", "save it").

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 read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds real behavioral context beyond that: a link to the full guide is returned, and an unrecognized client yields a catalog of available guides instead of an error.

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-loads the purpose in the first sentence, then adds invocation and fallback detail. The client-value enumeration is long but earns its place as the de facto enum for a schema that defines none.

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 return-value burden and does so by naming the steps and the guide link. Combined with the annotations and the fully documented single parameter, an agent has what it needs to call this correctly.

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 the baseline is 3, but the description goes further by enumerating concrete valid client values (gmail, outlook-new, outlook-classic, apple-mail, ios-mail, zoho-mail, thunderbird) that the schema only sketches with two examples. That materially improves correct value selection.

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 and resource (get install steps for adding an email signature) and scopes the source (Signatoro's install guides) plus the return value (steps with a link to the full guide). No sibling tool overlaps this purpose, so it is trivially distinguishable.

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?

Explains how to invoke it ('pass the app as client') and what happens for an invalid input ('an unknown client answers with the list of guides there are'), which covers the practical when/how. It does not name explicit alternatives, but no sibling tool provides install steps, so the routing job is done.

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?

Goes well beyond the readOnly/destructive annotations by disclosing quota behavior (Free plan 50 calls/month, Company unlimited), a caching anti-pattern, and a permission model: some fields are company-controlled and changeable only on signatoro.com by the owner, with companyControlled.howToChange naming who and where.

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-loads the core purpose, return format and the every-send rule, then layers quota and company-controlled context. Slightly long, and the final instruction about telling the person who changes company parts reads as agent-behavior coaching rather than tool definition, but nothing is padded.

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 still specifies the return shape (HTML and plain text, ready to append), plus quotas, the company-controlled field set, and the change path. An agent has everything needed to call and interpret this correctly.

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 is self-documenting, but the description adds genuine semantic content for 'short' (the cold-outreach cut: name, role line, one link) that the schema's 'full (default) or short' does not convey. Above the baseline 3 because it clarifies the mode's purpose, not just its values.

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 and resource (get the saved email signature), names the return formats (HTML and plain text), and distinguishes itself from update_my_signature and create_signature without needing the schema.

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?

Gives an explicit call-frequency rule (call on every email rather than caching) and names the alternative for the mutation case (use update_my_signature). It also scopes the 'short' mode to cold outreach, so an agent knows which variant to pick and when.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond them: the auth constraint ('Company owners only'), the composition of results (members plus pending invites), and the status values returned.

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?

A single dense sentence that front-loads the resource and then the scope and access constraint. Efficient with no filler, though packing the return fields into the same sentence makes it slightly heavy.

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 exists, so the description carries the return-value burden, and it does so by enumerating the returned fields and statuses. With one optional parameter fully documented in the schema and the access constraint stated, nothing needed for correct invocation is 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 already documents the slug/id format, so baseline is 3. The description adds semantics the schema lacks: that omitting the parameter widens the result to every company the caller owns, which is meaningful optional-parameter behavior.

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 and resource ('List the people in the signed-in owner's company') plus scope (joined members and pending invitations). It is clearly distinguishable from sibling mutations like add_member, remove_member, and resend_invite.

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?

Gives a clear usage condition: 'Company owners only' as a prerequisite, and 'Omit company to list every company you own' as the default behavior. It does not explicitly name an alternative tool for a different view, so it falls short of a 5.

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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds real value by disclosing the shape of each result (a layout plus a short description of what it shows and when it fits best), which partially compensates for the absence of an output schema.

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 short sentences, front-loaded with what the tool returns and followed immediately by the actionable next step. Nothing is redundant or padded.

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 parameterless, read-only lister with no output schema, the description conveys the substance of the return payload and how to use it. It does not state the container format (e.g., array vs. object) or the id format, a minor gap given the low 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?

The tool takes zero parameters, so there is nothing for the description to clarify; baseline 4 applies. The mention of a 'layout id' correctly refers to an output value used by a sibling tool, not an input here.

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 and resource ('List the signature layouts') and characterizes the content of each returned item. No sibling tool lists layouts, so it is unambiguously distinct from list_members or get_signature.

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?

Names the downstream action explicitly: the returned layout id is meant to be passed to create_signature, which tells the agent when this tool is the right starting point. It stops short of stating when not to call it, but the workflow context is 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?

Annotations already flag destructiveHint and idempotentHint, but the description goes well beyond them, disclosing the concrete effects (loss of company and signature access, invitation withdrawal), irreversibility, and an authorization/confirmation requirement.

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?

Dense, front-loaded single paragraph: the destructive/irreversible warning leads, then outcome branching, then confirmation, then authorization limits. No sentence is filler.

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 2-parameter mutation tool with no output schema, the description supplies everything an agent needs: safety profile, irreversibility, effect on both member states, and caller restrictions. No meaningful 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 100%, with both 'email' and 'company' fully documented (including the slug-or-id format for company). The description adds no parameter-level detail beyond that, so the baseline 3 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?

States a specific destructive verb and resource ('removes a person from the company') and immediately differentiates the two outcomes: joined member vs. pending invitation. An agent can distinguish this from add_member, list_members, and update_member_field at a glance.

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 preconditions and exclusions: 'Confirm with the user before calling', 'Company owners only', and 'Nobody can remove themselves or the primary owner.' These are exactly the conditions that determine whether the tool should be called and who may call it.

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 this is a non-read-only, non-idempotent, non-destructive call; the description adds genuinely useful context beyond that: the owner-only authorization requirement and the 7-day renewal behavior on expiry. It does not mention rate limiting or delivery-failure behavior for an email-sending 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?

One sentence with zero waste: action, target population, side effect, and permission gate are all front-loaded before any secondary detail.

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 two-parameter mutation with no output schema, the description covers the action, eligibility, expiry renewal, and authorization. It stops short of describing the result (e.g., what a failed resend returns), but nothing essential to calling it correctly is 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?

With 100% schema description coverage, the schema already documents both 'email' and 'company' including the slug-or-id format. The description adds no parameter-level syntax or format detail, so the baseline 3 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?

Specific verb (send again) + resource (invitation email) + precise scope: only people already invited to the company who have not yet joined. Distinguishable from siblings like add_member and remove_member without opening the schema.

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?

States the eligibility condition (person invited but not joined) and the permission prerequisite ('Company owners only'), which tells the agent when the call is valid. It does not name alternatives such as add_member when no invite exists, so it falls short of a 5.

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 flag destructiveHint=true, idempotentHint=false and openWorldHint=true. The description adds real behavioral context beyond that: the change triggers an email to joined members, re-sends the invitation for pending members, and is restricted to company owners. It does not say whether the previous value is recoverable beyond the destructive hint.

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 short sentences, each earning its place: the mutation scope is front-loaded, then the two side-effect paths, then the permission constraint. No filler.

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 4-parameter mutation with full schema coverage, no output schema and rich annotations, the description covers scope, auth and downstream effects adequately. Only minor gaps remain, such as confirming that unmentioned fields are left untouched.

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%, and the enum already restricts field to name/title/phone while the schema notes 'Empty clears it' for value. The description's field list and clearing behavior merely restate structured data, so the baseline 3 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?

States a specific verb and resource ('Change one field ... of a person's signature in the company') and enumerates the scope (name, title or phone), which cleanly separates it from the sibling update_my_signature and the broader add_member/create_signature tools.

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?

Names the prerequisite clearly ('Company owners only') and describes the resulting side effects, which tells the agent this is the right tool when a signature detail must be changed. It stops short of naming alternatives it supersedes (e.g., remove_member + add_member, or resend_invite), so no explicit when-not guidance.

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 flag destructive/open-world/idempotent, and the description adds real context beyond them: clearing via "", company-controlled fields returning in ignored with who changes them, mailbox propagation, quota accounting equivalent to get_signature, the held-back behavior when the month is used up, and the no-op case where nothing is written or counted.

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 the core purpose and patch rule, then quota/return behavior. It is dense and long, but nearly every clause carries actionable information (clearing, ignored fields, quota, no-op). Slightly overloaded for a single paragraph.

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 21 params, no required fields, and no output schema, the description compensates by explaining the return value (updated signature as HTML and text), the quota model, and the ignored-field feedback. Nothing an agent needs to call it correctly is 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 description coverage is 100%, so baseline is 3; the description raises it by explaining the patch semantics (only send changed fields, "" clears a field) and by naming the field groups. It adds meaning beyond the schema, though individual field-level nuances are left 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?

States a specific verb+resource and scope: "Save or change the signed-in person's own signature," then enumerates the fields it covers. The emphasis on "own" cleanly separates it from sibling update_member_field and create_signature, so an agent can route without opening schemas.

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 covers when it creates versus updates ("With nothing saved yet, this creates the signature"), the patch contract ("Give only the fields to change; the rest keep their saved values"), and the exclusion case (company brand items are set by the company owner on signatoro.com and land in ignored). That is when/when-not/alternatives in one place.

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