Appie.run

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

Adds genuinely non-obvious behavior beyond the annotations: no credit spend, immediate availability for inline text, and background processing for blog_url — the last being critical since a follow-up create_article may run before the sample exists. It does not say how to tell when background processing finishes, which would have completed the picture.

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 and the create_article linkage, then the cost and timing facts. Every sentence carries distinct information with no restatement of the 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 4-parameter write tool with no output schema, the description covers cost, timing, and the async path, which are the main risks. It omits whether repeated calls append or replace existing samples and what is returned, leaving a small but real gap for a non-idempotent 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?

With 50% schema coverage, the description partially compensates by framing text and blog_url as two alternative input modes, reinforcing the schema's "Omit when using blog_url" note. However, it adds nothing about the undocumented title and author_id parameters, so half the surface remains explained only by bare types.

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 immediately names the downstream consumer (create_article), which separates it from siblings like add_chatbot_content and update_brain. An agent knows exactly what this tool produces 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?

Gives clear usage context via the create_article dependency and distinguishes the two input modes (inline text vs blog URL). It stops short of naming when not to use it or which sibling to prefer for other content types, so it is clear context rather than explicit exclusions.

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 the mutation profile (readOnly=false, destructive=false, non-idempotent, openWorld), and the description adds real context beyond them: no credit spend, and url/sitemap content is crawled asynchronously rather than processed inline. The async background behavior is the key trait an agent needs and is disclosed. A minor gap remains: duplicate or re-submission behavior is not explained despite idempotentHint=false.

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 the credit-cost reassurance and the behavioral distinction between pasted and crawled content, then the polling instruction. Every sentence carries actionable information; nothing is padding.

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 mutation tool with no output schema and partial parameter coverage, this gives the agent the essentials: cost, sync vs async processing, and how to detect completion. The only meaningful omission is what a successful call returns (an id? a job handle?) and how to handle repeat submissions.

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 only 50%, so the description must carry weight. It does: it enumerates the four content_type values and maps each to how content arrives (text/article pasted in vs url/sitemap crawled), which covers the conditional-requirement logic that the schema only partially documents. Title remains unexplained and the article_id-to-content_type linkage is the schema's job.

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?

"Add knowledge to a chatbot" is a specific verb+resource pairing that clearly separates it from ask_chatbot (querying) and chatbot_status (checking progress). It does not explicitly name a sibling, so it stops just short of 5.

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 states when each content_type applies and prescribes the follow-up workflow ("Poll chatbot_status until training is complete"), which gives the agent a clear operational sequence. It does not name an alternative tool to use when adding content is the wrong choice, so there is no explicit exclusion.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds something annotations cannot express: the call is free of credit cost, which is genuinely useful for polling decisions. It still does not describe what status values exist or the response shape.

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 with zero filler, and the primary purpose is front-loaded ahead of the cost note. Nothing could be removed without losing 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?

There is no output schema, so the description must carry the return-value burden, and 'status and content' is thin — an agent cannot tell what statuses or fields to expect, nor whether content is truncated. For a simple one-parameter read this is adequate but leaves a real gap.

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 single parameter already carries a description pointing back to create_article, so the schema does the work. The tool description adds no further constraint on id (e.g., whether stale or foreign ids error), so 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 the resource (an article in this project) and what it returns (status and content), which tells an agent it is a read of one article by id. It is distinguishable from create_article, but it does not explicitly contrast itself with the other *_status sibling (chatbot_status) or other read 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 is only implied: the id description says it comes from create_article, so the natural flow is create-then-poll. The 'Does not spend credits' clause hints at when this is preferable to a costlier call, but no alternative tool is named and no explicit when/when-not guidance is given.

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 the mutation/open-world/non-idempotent profile, and the description adds two pieces of real value beyond them: a per-call cost of 1 credit and the fact that a reply is returned. It is consistent with annotations (no read-only claim). It stops short of saying whether the exchange is persisted or what happens on insufficient credits.

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 waste, with the core action front-loaded and the cost appended as a secondary fact. Nothing could be removed without losing 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?

For a simple three-parameter, no-output-schema tool the essentials are present, but the conversation/session model is the main behavioral unknown and is left entirely to a one-line schema note. It is adequate but leaves gaps around session reuse and failure modes.

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?

Only 33% schema coverage — chatbot_id and message are undocumented in the schema, and session_id carries its own description ("Omit to start a new conversation"). The description implies chatbot_id/message semantics through its wording but adds nothing about conversation continuity, message size, or how session_id interacts with follow-ups.

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 a specific verb and resource ("Send a message to a project chatbot and return the reply"), which is clearly distinct from siblings like create_chatbot or add_chatbot_content. It does not explicitly say how it differs from those siblings, but the action is unambiguous.

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 by the verb — an agent can infer this is the tool for querying a chatbot. There is no explicit when-to-use versus add_chatbot_content (feeding content in) or create_chatbot (provisioning), and no stated prerequisites or exclusions.

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, so the safety profile is covered. The description adds a genuinely useful cost note ('Does not spend credits'), which contextualizes it against credit-consuming siblings like ask_chatbot, but says nothing about what the status values are, whether incomplete training produces partial data, or response shape.

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 with zero filler, and the core purpose is front-loaded before the cost caveat. Slightly under-specified rather than 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 simple read-only status lookup with one obvious param, this is close to adequate, but with no output schema the description should hint at what is returned (status values, source entries) and the requirement that the chatbot exist. As written it leaves the return value entirely opaque.

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 parameter, chatbot_id, with 0% schema description coverage; the description never refers to it. The name and integer type make its meaning largely self-evident, but the description adds no guidance such as where the id comes from (e.g., list_chatbots).

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: retrieves training status and sources for a single chatbot, which is clearly distinct from list_chatbots (plural listing) and create_chatbot (mutation). It does not mention what 'sources' concretely are, but the intent is unambiguous.

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 — an agent infers this is for checking training progress. There are no explicit when/when-not conditions, no mention of alternatives like list_chatbots for enumeration, and no prerequisites such as a chatbot needing to exist or be training.

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=false and non-idempotent, so the mutating nature is covered; the description adds genuinely new behavioral facts: credit costs (100 light / 500 deep) and asynchronous execution requiring polling. It stops short of saying whether the call spends credits immediately or only when generation starts, and doesn't warn that repeat calls create separate articles and separate charges.

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 the action, then the author sourcing rule, then the cost model, then the async follow-up. Every sentence carries distinct information and none restates the schema verbatim.

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 async creation tool with no output schema, it covers the important unknowns: cost, asynchrony, and the polling path. The one gap is that it never says what the call returns (presumably an article id) that article_status would be polled with, leaving the agent to infer the handle from the sibling's 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 coverage is 100%, so the baseline is 3; the description earns above that by mapping article_type values to credit costs, which the schema only expresses as word counts. The author_id default is repeated rather than extended, and topic gets no elaboration 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?

"Start an article in an author's voice" gives a specific verb and resource, and the surrounding sentences tie it to list_authors and article_status, so it reads as the entry point of a generate-then-poll workflow. It doesn't explicitly rule out any sibling, but no sibling competes for the same action, so differentiation is effectively implicit.

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 states exactly how to supply the author (pass author_id from list_authors, or omit to use the active author) and prescribes the follow-up step ("Poll article_status"). What's missing is any guidance on choosing between article types beyond cost, or on when not to use this tool.

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 annotation set only tells the agent this is a non-destructive, non-read-only, non-idempotent write in a closed world. The description adds genuinely useful behavior: 'Does not spend credits' and the validation floors for bio and sample. It does not say what happens on duplicate author names or what the call returns, which keeps it below 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?

Four short sentences, front-loaded with the action, followed by the cost note and the two constraints. Every sentence carries information an agent needs, with 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 five-parameter mutation tool with no output schema, the description covers purpose, credit cost, validation constraints, and downstream use. It omits return value and duplicate-name behavior, but the core invocation context is present.

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%, so the baseline is 3. The description repeats the bio and sample length constraints that are already in the schema, but it does add the important semantic point that sample_content feeds create_article's voice. It leaves author_name, sample_title, and is_active semantics 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?

The description opens with a specific verb and resource: 'Create an author profile.' It also points at the downstream consumer, create_article, which helps an agent place the tool. It does not explicitly distinguish this from the sibling add_author_sample, so it stops short of a 5.

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 makes clear this is the tool for creating a new author and explains the role of the optional sample in enabling create_article to use the author's voice. There is no explicit statement of when to prefer add_author_sample or when not to call this, so the guidance is clear but incomplete.

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-destructive, non-idempotent, closed-world write, so the bar is lower. The description does add genuinely useful cost context ('Does not spend credits'), but says nothing about what happens on a duplicate name, what identifier is returned for later add_chatbot_content calls, or any auth requirements — gaps that matter for a create 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, all front-loaded: what it does, what it costs, and what to do next. No filler or restated name/title.

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 workflow chain and cost note cover the most important context, and the lack of an output schema means return values are not required. However, an agent still cannot tell whether it needs the created chatbot's ID/name for the follow-up add_chatbot_content call, which is the central post-condition of this 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?

Schema coverage is only 50%: temperature and system_prompt are documented in the schema, but 'name' and 'openai_model' carry no description at either layer. The description adds nothing about parameters, leaving the model enum choice and the name-uniqueness question entirely to 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 a specific verb and resource ('Create a chatbot for this project'), which is unambiguous against most siblings, and the added workflow sentence distinguishes it from add_chatbot_content and ask_chatbot. It stops short of naming what a chatbot is scoped to beyond 'this project', but the core action is clear.

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 three-step sequence: create here, populate with add_chatbot_content, then query with ask_chatbot — that is real routing guidance an agent can act on. It lacks any exclusion or prerequisite (permissions, uniqueness of name), so it stops 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 a non-read-only, non-destructive, non-idempotent mutation, so the safety profile is covered. The description adds genuinely new behavioral context the annotations cannot convey: a 1-credit creation cost plus a 0.001-credit per-click cost, which is decision-relevant for an agent. It stops short of 5 by not covering code-collision behavior or auth requirements.

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 action and followed by the cost model; every sentence contributes information an agent needs and there is 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 two-parameter creation tool with full schema coverage, no output schema, and annotations covering mutation semantics, the description supplies the key missing decision factor (cost). It is only slightly short by not indicating what the call returns (e.g., the short URL) or failure modes like a taken custom code.

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 long_url and code fully documented including format constraints, so the schema carries parameter semantics. The description adds nothing about either parameter, making the baseline 3 correct.

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 a short link'), scoped to 'this project', which is unambiguous and clearly distinct from the sibling link_stats (read/analytics) tool. It doesn't explicitly name a sibling or contrast with one, keeping it just short of 5.

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 by the verb; there is no statement of when to create a link versus when to inspect existing links via link_stats, and no prerequisites or exclusions. Comparable to the calibration MID case where a bare 'update X settings' sentence earned a 2.

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?

Adds substantial context beyond the annotations: an explicit credit cost (2 credits), a hard statement that no write to Reddit occurs, and the fact that the agent/user must complete the posting manually at source_url. This complements the provided non-destructive/non-open-world hints with cost and side-effect scope the annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the core action and scope, then cost, then the critical limitation and manual step. 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 single-parameter tool with no output schema, it covers the essentials: what is produced (a draft), what it costs, and what it does not do. A brief note on what the response returns (e.g., the draft text and source_url) would close the remaining gap.

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 0%, so the description must compensate; it does so only partially, clarifying that the id refers to a single mention drawn from list_reddit_mentions (implying one id, not a list). It never states the parameter's type, format, or where to source the integer beyond naming the originating tool.

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+resource+scope: "Create a Reddit reply DRAFT only for one mention." It also anchors to the sibling source tool (list_reddit_mentions) and explicitly negates the scope an agent might wrongly infer ("Never posts to Reddit"), making it distinguishable from any publish or list tool.

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 names the prerequisite path (a mention obtained from list_reddit_mentions) and the required follow-up ("Copy the draft and paste it yourself at source_url"), which is clear context for when to use it. It stops short of explicit exclusions such as what to do if you want a post rather than a draft, since no such sibling exists.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds a genuinely non-redundant behavioral fact — 'Does not spend credits' — which is a cost constraint an agent cannot infer from structured fields.

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 resource and its contents, then consumers, then the cost note. Nothing is repeated from the schema or annotations and 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?

There is no output schema, and the description compensates by enumerating the Brain's constituent fields (website, about text, brand voice, key messages, ideal customer, competitors), effectively serving as a return-value summary. Combined with the annotation-covered safety and cost profile, 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The description instead spends its words on what comes back, which is the more useful place for them 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?

Specific verb ('Read') plus specific resource ('this project's Brain'), followed by an enumeration of exactly what the Brain contains (website, about text, brand voice, key messages, ideal customer, competitors). This makes it unmistakable against the sibling update_brain, whose verb signals mutation while this one signals retrieval.

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 concrete consumers ('Content Writer and chatbots use this context'), which tells an agent the downstream purpose of the read. It does not explicitly state exclusions or contrast against update_brain, but the read/update split is self-evident and the 'does not spend credits' line removes a common hesitation about calling 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context no annotation provides: this call is free, while a scheduled scan costs 30 credits and an email lookup costs 5, which shapes how an agent budgets calls.

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 purpose front-loaded and the zero-cost property immediately after. The two credit-comparison sentences are useful but slightly tangential and could have been collapsed into one line without loss.

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 list tool with no output schema, the description covers purpose and cost but says nothing about what a returned profile contains, whether results are paginated or scoped to the whole project, or how large the list may be. An agent knows whether to call it, but not what to expect back.

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 and the baseline applies. The extra sentences about credit costs are not parameter guidance but do not detract from an otherwise complete parameter story.

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 gives a specific verb and resource ('List LinkedIn profiles this project tracks') and implicitly separates itself from list_linkedin_leads by naming profiles rather than leads. It does not explicitly call out the sibling it differs from, so it stops short of full differentiation.

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 only usage signal is cost-based ('Does not spend credits'), which hints that this is the free way to inspect tracked profiles versus paying for scans or lookups. There is no explicit when-to-use or when-not-to-use statement, and no pointer to list_linkedin_leads or set_linkedin_profile as 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 credit-cost disclosure and the lazy-initialization fallback are genuinely valuable behavioral context. However, "those details are saved and returned" describes a conditional write, which conflicts with the declared readOnlyHint=true, so the safety signal the agent receives from structured fields is unreliable here.

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 what is returned, then cost, then the fallback edge case. Every sentence carries information, though "the Brain" is left unexplained and the conditional clause takes a second read.

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 and no parameters, the description does the necessary work: it enumerates the returned fields and warns about the initialization side effect. The remaining gap is that it does not say what an empty result looks like when neither saved settings nor Brain company details exist.

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 the baseline is 4. There is nothing to document beyond the absence of inputs, and the description correctly implies no caller-supplied arguments are needed.

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 with the exact contents returned: Reddit keywords, competitors, and reply guidance. It is clearly distinguishable from write-side siblings like update_reddit_settings and from list_reddit_mentions, though it does not name those alternatives explicitly.

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?

"Read" implies this is the retrieval path versus update_reddit_settings, but no alternative is named and no when-not condition is given. The credit-cost note gives useful context for choosing it, yet the agent is left to infer the routing.

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, and closed-world behavior. The description adds useful credit-cost context beyond those annotations by clarifying that reading stats does not spend credits, though it does not discuss permissions 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?

The description is three concise sentences, front-loads the purpose, and includes the cost caveat without wasted wording.

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 rich annotations and full schema coverage, the description is largely complete: it identifies the returned data and notes credit behavior. It could be slightly richer about the returned series, but no output schema exists to rely on.

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 explains both parameters, including that `id` comes from `create_short_link` and `code` is used when `id` is omitted. The description adds no parameter-specific meaning 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 clearly states what is returned: click totals and a 30-day series for one short link in this project. It identifies the resource and scope but does not explicitly distinguish itself from sibling tools or name an alternative.

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: this tool reads stats for a single short link, and the description notes that reading stats is free while link clicks cost credits. It does not explicitly state when to use this versus other tools or when not to use 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 readOnly, idempotent and non-destructive, so the description correctly doesn't repeat those. The genuinely useful addition is the cost fact ('does not spend credits'), which matters in a toolset where other calls presumably do cost credits. It doesn't say anything about result size or ordering.

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 clauses, front-loaded with the resource and scope, followed by the cost caveat. 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?

With no parameters and no output schema, the description carries the burden of hinting at the return shape, and it does so partially by naming the readiness flag. It stops short of saying what other profile fields come back or roughly how many authors, which would help an agent decide whether to page or reuse the result.

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 to document; baseline is 4. The description correctly avoids inventing filtering options.

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 author profiles') scoped to 'this project', and adds the key payload detail that each entry carries a create_article readiness flag. This clearly separates it from create_author and add_author_sample.

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 mention of readiness for create_article implicitly tells the agent to call this before authoring, and 'does not spend credits' signals it is a cheap pre-check. It lacks an explicit 'use X instead when...' routing statement, so it stops short of top marks.

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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds cost behavior ('does not spend credits') and the nature of the returned data (knowledge readiness), which is value beyond structured fields, though it says nothing about result size or ordering.

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, the resource/scope front-loaded and the cost caveat immediately after. Nothing is wasted or buried.

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 parameters and no output schema, the description carries the burden of explaining return values, and it does so at a high level (chatbots plus knowledge-readiness status). A bit more on what 'knowledge ready' means or result shape would make it fully self-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?

The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. The schema is fully closed (additionalProperties: false), so no gaps remain.

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 chatbots') scoped to 'this project', plus the extra dimension returned ('whether their knowledge is ready'). It is distinguishable from siblings like create_chatbot or ask_chatbot, though it never explicitly contrasts with the singular chatbot_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?

'Does not spend credits' implicitly signals that this is the cheap way to check chatbot status versus credit-consuming operations such as ask_chatbot, but no explicit when-to-use/when-not or named alternative is given. Usage must be inferred.

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 readOnly, idempotent, non-destructive and closed-world. The description adds genuinely new behavioral context: no credit cost, and that email/phone appear only 'when enrichment has found them' — i.e. output fields are conditional. Missing pagination or truncation behavior beyond the schema'd limit.

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 resource and scope, second sentence carrying the cost signal. Nothing redundant.

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-required-param list tool with rich annotations and a fully described schema, the description covers scope, enrichment caveat and cost. No output schema exists, so the return shape is only lightly sketched (leads with optional email/phone) but adequate.

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 limit default/max and tracked_profile_id scoping fully documented in the schema. The description adds no further parameter semantics, so 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 ('List leads from tracked LinkedIn profiles') and clarifies the payload includes enrichment fields (email/phone). It is distinguishable from get_linkedin_profiles and set_linkedin_profile, though it does not name those siblings explicitly.

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: 'Does not spend credits' hints this is the cheap, safe way to see leads, but it never states when to pick this over get_linkedin_profiles or what happens if no profiles are tracked. No explicit exclusions or alternatives named.

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, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral context: a once-per-day scan cadence, a 10-credit cost, and graceful degradation via scan_skipped when the balance is too low. It stops short of describing ordering, staleness of results, or what happens on repeat calls within the same day.

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 carrying distinct information: what is returned, the cost/cadence constraint, and the low-balance failure mode. The core purpose is front-loaded with 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?

With no output schema, the description does the right thing by naming key response fields (credits_remaining, scan_skipped) and the included reply draft. It leaves some gaps — the shape of a mention, sorting, and whether cached results are returned on repeat calls — but an agent has enough to invoke it 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?

There is a single parameter (limit) with 100% schema description coverage, including the default of 20 and maximum of 50. The description adds nothing about how limit interacts with the daily scan or credits. Per the rubric, full schema coverage sets the baseline at 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 opens with a specific verb and resource: 'List Reddit threads for the saved keywords,' plus the notable inclusion of 'the latest reply draft.' The verb 'List' clearly separates it from the mutating sibling draft_reddit_reply, but the description never names that sibling or explicitly draws the line between listing mentions and acting on them.

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 implies when the tool is appropriate (to see threads for saved keywords) and gives a strong operational constraint: a scan runs at most once per day and costs 10 credits. However, there is no explicit statement of when NOT to use it versus draft_reddit_reply or get_reddit_settings, and no prerequisite (e.g., keywords must be configured) is stated.

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 the safety profile (readOnly=false, destructive=false), and the description goes beyond them with a genuinely useful cost model: no credits now, 30 credits for the scheduled scan, 5 for a lead email lookup. That is exactly the kind of downstream consequence annotations cannot express. Minor tension: 'add or update' reads as an upsert while idempotentHint=false is not reconciled.

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 the action and required argument, then cost. No filler, though the two separate credit sentences could be compressed into one and the 'lead email lookup' cost is only loosely tied to this tool's own behavior.

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 mutation tool with no output schema, the description covers cost but omits the essentials an agent still needs: what the call returns, what happens when the URL already exists (add vs. update semantics), the untouched 'name' parameter, and whether a lead lookup is triggered here or 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 67% (profile_url and tracking_enabled are documented in the schema itself), so the baseline is 3. The description restates the required argument and the tracking_enabled default rather than adding format or behavior detail, and it is silent on the 'name' parameter, which is undocumented in both places.

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 opening sentence names a specific verb pair and resource ('Add or update a tracked LinkedIn profile'), and the required argument is stated immediately. It implicitly separates itself from the read-side sibling get_linkedin_profiles, though it never names that sibling explicitly.

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?

'Pass profile_url. Optional tracking_enabled, default true.' gives call-shape guidance, and the credit note hints at cost trade-offs, but there is no statement of when to prefer this over get_linkedin_profiles / list_linkedin_leads, nor any exclusion or prerequisite (auth, existing-profile conflicts).

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-destructive, non-idempotent, closed-world mutation, so the safety profile is covered. The description adds genuinely useful context beyond that: no credit cost and that omitted fields are left untouched. It does not explain merge vs replace behavior for nested objects/lists or what an update response looks like.

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 and cost, with no filler. The enum listing at the end is redundant with the schema and takes space that could have gone to the undocumented fields.

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?

A 19-parameter nested mutation with no output schema and near-zero schema descriptions needs far more: what the Brain represents, whether nested brand_voice and arrays merge or replace, and which fields are mutually relevant. The definition covers only the cheapest facts, leaving an agent to guess at the rest.

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% across 19 parameters, so the description should compensate and largely does not. The only parameter detail given (brand_voice 0-100, category and icp_gender enums) merely restates what the schema already encodes, while competitors, key_messaging, sitemap_url, shopping_feed_url, and the ICP fields are never explained.

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 the read counterpart get_brain exists among siblings, so the agent can place it. 'Brain' is domain jargon that isn't defined, and no sibling is named explicitly, so differentiation is inferred rather than stated.

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 a concrete invocation guideline (partial-update semantics) and 'Does not spend credits' hints at cost considerations. However, it never says when to prefer this over get_brain, what prerequisites exist, or whether an empty call is valid.

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 establish that this is a non-destructive, non-read-only update, so the description adds meaningful context beyond them: no credit cost, partial-field updates, and a 25-item cap per list. It still leaves ambiguous whether sending a list replaces or appends to existing values and does not discuss 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?

Four short, front-loaded sentences carry the key scope, cost, partial-update, and limit information with 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 three-optional-parameter settings mutation with no output schema, the description covers the essential operational facts: what changes, no credit cost, partial updates, and list limits. It is mostly complete, though it could clarify list replacement semantics and why idempotency is marked false.

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 baseline is 3. The description adds useful meaning by stating that only fields to change should be sent and that each list is capped at 25 items.

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 uses a specific verb, 'Set,' and names the Reddit settings being changed: keywords, competitors, and reply guidance. This clearly distinguishes the mutation tool from the sibling read tool, get_reddit_settings, without requiring 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?

It gives useful operational guidance: send only fields to change, and it clarifies that the call does not spend credits. It does not explicitly compare against get_reddit_settings or draft_reddit_reply, but the intended usage context is clear.

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