Appie.run

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

With no annotations, the description carries the full burden, and it does disclose the key async trait: text is usable immediately while a blog URL is processed in the background. However, it says nothing about permissions, whether adding a sample mutates or overwrites the author's existing voice, or any limits on sample count.

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 with no filler, and the primary purpose (feeding create_article's voice) is front-loaded before the synchronous/asynchronous 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 4-parameter mutation tool with no annotations and no output schema, the description covers the core input duality and downstream purpose but omits the meaning of title and author_id, what the call returns (e.g. a sample identifier), and whether existing samples are affected.

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 50%: content and blog_url are already documented in the schema (including the 100-character minimum and the omit-when-using-blog_url rule), and the description essentially restates the text-vs-URL dichotomy. The title and author_id parameters receive no semantic elaboration in either place, 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?

States a specific verb and resource ('Add a writing sample to an author') and names the downstream consumer and sibling, create_article, that the sample feeds. An agent can distinguish this from add_chatbot_content or create_author 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?

The clause 'so create_article can use that voice' gives a clear reason to call this tool rather than another, establishing the author-voice use case. It stops short of stating exclusions or contrasting with the sibling add_chatbot_content, which would be needed for 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?

With no annotations, the description carries the full burden and delivers the key operational trait: url/sitemap ingestion is asynchronous and requires polling chatbot_status until training completes. It omits authorization requirements, whether content is additive or replaces existing knowledge, and any rate or size limits.

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?

Four short sentences, front-loaded with purpose then mode behavior then the follow-up action. Every sentence adds information; no repetition of the name or 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 six-parameter mutation tool with no annotations and no output schema, the description covers the critical async-return path (poll chatbot_status until training completes) and the mode-dependent inputs. Minor gaps remain around chatbt_id semantics, title usage, and whether repeated adds accumulate.

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?

At 50% schema coverage the description must compensate, and it does for content_type by tying each enum value to an ingestion path ('Text and articles are pasted in. url and sitemap are crawled in the background'), which explains why url/content/article_id are conditionally required. It says nothing about chatbot_id or title.

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 ('Add knowledge to a chatbot') and enumerates the four content modalities it accepts, which cleanly separates it from siblings like create_chatbot, ask_chatbot, and add_author_sample. An agent can identify the tool's job 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?

Explains the mode selection (text/article are pasted, url/sitemap are crawled in the background) and even routes the agent to chatbot_status for polling, which is clear usage context. It stops short of stating when NOT to use this tool or naming a true alternative for bulk knowledge ingestion.

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?

With no annotations at all, the description carries the full behavioral burden and only partly meets it. 'Does not spend credits' is a genuinely useful cost/behavior disclosure, but it says nothing about whether this is a pure read, whether callers must poll while an article is still processing, or how an unknown/not-yet-ready id behaves.

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 only by the one non-obvious fact (no credit cost). No filler, 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?

For a one-parameter, fully documented read tool with no annotations and no output schema, the description is adequate but thin: it promises 'status and content' without indicating what statuses exist or what the content payload looks like, leaving the caller unable to anticipate the response 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?

Schema coverage is 100% with a single well-documented id parameter ('Article id returned by create_article'), so the schema already does the work. The description adds no format, range, or origin detail beyond it, matching the 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?

States a specific resource ('an article in this project') and the two things it returns (status and content), which is enough to distinguish it from the write-side sibling create_article. It is a noun phrase rather than an explicit verb ('get'), so it is clear but not maximally crisp.

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?

Usage is implied rather than stated: the parameter doc ties it to create_article, and 'Does not spend credits' hints it is the cheap alternative to a credit-consuming operation, but there is no explicit when-to-use or when-not-to-use guidance against siblings like chatbot_status.

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?

No annotations are supplied, so the description carries the full burden. It does disclose a genuine behavioral trait the structured fields do not: each call costs 1 credit. However it omits whether a session persists across calls, whether the call is expensive/slow, auth requirements, or rate limits.

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, zero filler, with the action stated first and the credit cost held back as a secondary note. Nothing to trim.

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 3-parameter tool with no output schema and no annotations, the definition covers the basic contract and the cost, but leaves out session semantics, error/rate-limit behavior, and anything about response shape or latency that an agent would want before committing credits.

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 only 33% (only session_id is documented), and the description adds nothing about message or chatbot_id. It also never explains that session_id enables multi-turn continuation, which is the main parameter subtlety 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 (send a message) plus resource (a project chatbot) and what comes back (the reply). It is distinguishable from siblings like create_chatbot, chatbot_status and add_chatbot_content, but it never explicitly names those alternatives.

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 when-to-use guidance is given: nothing on when to ask a chatbot versus checking chatbot_status or feeding content via add_chatbot_content, and no prerequisites (e.g. that the chatbot must exist and be trained). The only condition-like signal, session omission, lives in the schema.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses a side-effect trait ('does not spend credits'), which implies a safe read, but it says nothing about permissions, rate limits, or what 'sources' contains. The credit note is genuine added value but not enough for a mutation/read-heavy readout.

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 the purpose and followed by the cost caveat. No filler; every clause earns its place.

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 is a simple single-parameter read with no output schema, so the description need not explain return values. Purpose plus the credit note covers most of what an agent needs, though the meaning of 'sources' is left unstated.

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?

One required parameter with 0% schema description coverage, so the description must compensate. 'for one chatbot' implies chatbot_id selects a single chatbot, but no format, type, or lookup guidance is added beyond that inference.

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 the resource ('one chatbot') and what is returned (training status and sources), which is a concrete verb+resource pairing. It is distinguishable from siblings like article_status (different resource) but does not explicitly name or contrast any sibling.

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 statement of when to use this versus alternatives such as ask_chatbot or get_brain. The only usage-adjacent cue is 'Does not spend credits,' which is a cost note rather than routing 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?

With no annotations, the description carries the full load and does real work: it discloses asynchronous generation, per-type credit costs (100 vs 500), that charging happens when generation runs, and the default author behavior. It doesn't explain what the response returns (e.g., the article identifier needed to poll article_status), which is a notable gap for an async creation tool.

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?

Five short, front-loaded sentences: purpose first, then the author input, then the async/cost model, then the next action. Every sentence carries operational information and none 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 an async creation tool with no annotations and no output schema, the description covers the essentials: what it creates, the inputs' sources, cost, asynchrony, and the polling step. It stops short of stating what comes back or how to identify the created article, which leaves one gap in the invocation loop.

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 adds value beyond the schema by telling the agent where author_id comes from (list_authors) and tying article_type to concrete credit costs and the default. The topic parameter gains nothing beyond its schema text, but the other two are meaningfully enriched.

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 ('Start an article in an author's voice') and immediately distinguishes itself from siblings by naming list_authors for the author input and article_status for follow-up. An agent can tell what this does and where it sits in the workflow 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?

Explicitly says to pass author_id from list_authors or omit it to use the active author, and to poll article_status for completion, which are the exact routing decisions an agent must make. What is missing is any when-not guidance (e.g., failure conditions or credit-exhaustion behavior), so it stops just short of the top score.

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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose two real constraints (bio >= 50 chars, sample >= 100 chars), but says nothing about whether names must be unique, whether creation is idempotent, what permissions are needed, or what a failed validation returns.

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 with the core action first, then the two constraints, then the optional-field rationale. Nothing is padded, though the bio length rule is repeated verbatim from the schema, which costs a few 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?

For a 5-parameter creation tool with no annotations and no output schema, the description covers the core action and constraints but leaves the return value (new author identifier), uniqueness behavior, and the sample_title/sample_content pairing unexplained. Adequate but with clear gaps.

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 60%: bio and sample_content are documented in-schema, while author_name, sample_title, and the is_active default are covered partly or not at all. The description restates the length rules but does add meaning by tying sample_content to how create_article will use the voice, though it never clarifies that sample_title pairs with it.

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 ('Create an author profile'), which is immediately distinguishable from reads like list_authors or mutations like add_author_sample. It does not explicitly contrast itself with the related sibling add_author_sample, which also attaches a sample to an author, leaving a small ambiguity about which entry point to use.

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 gives useful downstream context ('so create_article can use this voice'), which implies when the optional sample is worth providing. It does not state prerequisites, ordering relative to add_author_sample, or when to prefer list_authors/update paths, so usage is only 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that creation is free and that the chatbot starts empty (needing content before asking), which are useful traits. However, it omits permissions, reversibility, what creation provisions, and default behaviors, leaving significant gaps for a mutation tool.

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 core action, then cost, then next steps. Every sentence adds distinct value with no filler or 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?

For a creation tool with no annotations and no output schema, the description covers purpose, cost, and the follow-up workflow, which is helpful. Yet it leaves parameter semantics and behavioral specifics (auth, defaults, return info) unaddressed, so an agent must infer too much to call it confidently.

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 only 50%; 'name' and 'openai_model' lack descriptions in the schema. The description mentions no parameters at all, so it fails to compensate for the undocumented half. An agent cannot learn from the description what 'name' expects or what the model enum means.

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 states a specific verb ('Create') and resource ('chatbot for this project'), making the purpose immediately clear. It references sibling tools to indicate the creation context, but does not explicitly differentiate this creator from other create_* tools beyond the resource name.

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?

It gives a clear post-creation workflow: use add_chatbot_content to add knowledge, then call ask_chatbot. It also notes that creation is free. There is no guidance on when not to use this tool or on alternative creation paths, but the intended context is well-established.

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?

With no annotations, the description carries the full burden. It discloses the credit cost, which is genuinely useful behavioral context. However, it does not state whether links are permanent, whether the short domain matters, or what the response contains.

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 very short sentences, front-loaded with the purpose and followed by the cost. No waste.

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 two-parameter creation tool with full schema coverage and no output schema, the description is adequate but thin. It omits any mention of the returned short link or error behavior, leaving minor gaps.

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 both parameters fully described in the schema. The description adds no parameter detail beyond that, so the baseline of 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+resource: 'Create a short link'. The addition 'for this project' implies scoping. It is clear enough, though it does not explicitly distinguish itself from create_article or create_author beyond the resource name.

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. It does not mention link_stats, which is the obvious companion tool for inspecting links, nor any precondition or context.

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?

With no annotations, the description carries the full burden. 'Read' signals a non-mutating operation and the enumeration of returned fields is genuinely useful given there is no output schema, but it says nothing about permissions, scoping to a specific project, or error/empty states.

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 tight sentences, zero filler, with the core purpose front-loaded and the audience note secondary. Every clause earns its place.

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 zero-parameter read with no output schema, the description compensates by enumerating the returned content, which is the key thing an agent needs. The only gap is the absence of scope/auth context or guidance relative to update_brain.

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 per the baseline there is nothing for the description to clarify beyond the schema, which already declares an empty object.

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 clear verb ('Read') and resource ('this project's Brain') and enumerates exactly what the Brain contains (website, about text, brand voice, key messages, ideal customer, competitors). The read framing implicitly separates it from the update_brain sibling, though that sibling is never named.

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?

It notes that 'Content Writer and chatbots use this context', which implies when the content is relevant, but it gives no explicit when-to-call guidance, prerequisites, or direction on choosing it over update_brain or the various add_* content tools.

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?

No annotations are provided, so the description carries the full burden. It does disclose a real behavioral fact beyond the schema — 'Does not spend credits' — which tells the agent this call is effectively free and safe to repeat, and the read-only nature is strongly implied by 'click totals' and '30-day series'. It stops short of stating auth/permission needs or whether data is cached/live.

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, zero filler, with the payload described first and the cost reassurance second. Nothing is wasted.

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 two-parameter read tool with no output schema, the description covers what the response contains (totals plus a 30-day series) and the cost profile. The remaining gap is a lack of precision on return format and whether the series is daily counts, which is minor for this 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%, so both id and code are already documented including the 'used when id is omitted' fallback rule. The description only implies 'one short link' and adds no lookup-precedence or format detail 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?

The description names the exact resource (one short link) and the exact payload (click totals plus a 30-day series), so an agent can immediately tell this is the analytics read for short links. It does not name a sibling alternative, but the specificity of the returned data is enough to separate it from create_short_link and the chatbot/article 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?

Usage context is implied rather than stated: you use it to get metrics for a single link, and 'in this project' hints at scoping. There is no explicit when-to-use, when-not-to-use, or pointer to an alternative for aggregate or cross-link stats.

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?

No annotations are provided, so the description carries the full burden. 'List' implies a read-only operation and the description helpfully discloses that results include a readiness flag, but it says nothing about ordering, pagination, scope limits, or permissions.

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 tight sentence with the resource front-loaded and the extra value (readiness flag) trailing. 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?

There is no output schema, so the description must convey return content, and it does so in outline (author profiles plus readiness). For a parameterless read tool this is nearly complete, missing only pagination/scale behavior.

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 disambiguate; the baseline for parameterless tools 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 ('List') and resource ('author profiles for this project'), and adds the distinguishing detail that each entry includes readiness for create_article. It is clear what the tool returns, though it does not explicitly contrast itself with siblings like create_author or article_status.

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?

Usage is only implied: the mention of 'ready for create_article' hints this is a pre-flight check before article creation, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many sibling tools.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses that the response includes a knowledge-readiness flag, which is behavioral value beyond a bare list, but it says nothing about scope limits, pagination, or whether the operation is read-only.

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 front-loaded sentence with no waste that conveys both the resource and the notable return 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 no-parameter, no-output-schema list tool, the description covers what is returned (chatbots plus readiness) adequately. Minor gaps around read-only nature and result scoping, but nothing essential 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?

The tool takes zero parameters, which is the baseline-4 case; there are no parameter semantics to document and the schema is trivially complete.

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 ("List chatbots in this project") and clarifies one dimension of the returned data (knowledge readiness). It is clearer than a bare tautology, but it does not explicitly differentiate itself from siblings like chatbot_status or create_chatbot.

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?

There is no when-to-use guidance, no conditions, and no mention of alternatives such as chatbot_status. The agent must infer that this is the enumeration tool from the name 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?

With no annotations, the description carries the full behavioral burden. It discloses the partial-update contract, the 0-100 range for brand voice values, and the allowed category/gender values, but it says nothing about whether omitted fields are preserved, whether supplying brand_voice replaces all four axes or merges, or what permissions are needed. Those are material gaps for a mutation tool with nested objects.

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 dense sentences, action stated first followed by the partial-update rule and the constrained vocabularies. No filler, no repetition of the tool name.

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 19-parameter mutation tool with nested objects, no annotations, and no output schema, the description is far too thin. It covers two enumerations and one numeric range but leaves the bulk of the surface, the merge/replace semantics of brand_voice and competitors, and the absence of required fields unexplained.

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 only 11% (about_website and the nested brand_voice range), so the description is expected to compensate for 17 undocumented parameters. Instead it spends its words restating the category and icp_gender enums that the schema already encodes, and the brand_voice range that the schema already states, while competitors structure, icp_age_range, icp_geography, sitemap_url and the brand_* fields remain unexplained.

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 ('Update this project's Brain') and immediately clarifies the partial-update contract with 'Send only the fields to change.' It contrasts implicitly with get_brain, but never names the sibling or explains what a 'Brain' object actually holds, so an agent unfamiliar with the domain must infer scope.

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?

'Send only the fields to change' is genuine usage guidance for a PATCH-style tool, which is more than most definitions offer. However, there is no statement of when to prefer this over get_brain, no prerequisites, and no indication of whether it is safe to call repeatedly.

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