Mentionry

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

With no annotations, the description carries the burden and it adds useful behavior: results are classified by winnability and rationale, and competitors are explicitly excluded from their own results. The read-only nature is implied by 'Find', though side effects, auth, and rate limits are not addressed.

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 tightly worded sentences front-load the core function and then add an important edge-case rule. No filler or redundancy; every clause contributes meaning.

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 two simple parameters, the main invocation is inferable, and the winnability classification gives some sense of return content. However, with no output schema, the description does not specify the output shape or define 'realistically winnable', and it omits usage context relative to sibling tools.

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%: only competitors has a schema description, and the description maps 'you' to the domain parameter. It clarifies that competitors are the source of gap analysis, but it adds no format, example, or requirement details for domain beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses a specific verb ('Find') and names the exact resource: pages linking to competitors but not to the user's domain. It also describes the unique output classification (winnable and why), which separates it from siblings like discover_competitors and find_prospects.

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 is given on when to use this tool versus alternatives such as discover_competitors or find_prospects. The description implies a backlink-gap use case but never states prerequisites, exclusions, or which sibling to choose instead.

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 bears the full burden. It discloses useful behavioral content: step-by-step behavior, returned data, billed vendor steps, and current blockers. However, it does not explicitly state side effects (e.g., whether this tool is read-only or can trigger agent execution), which is a meaningful gap for an agent inspection 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?

All information is packed into one front-loaded sentence, with the primary purpose first and supporting output details after. It is somewhat dense, but every clause adds distinct 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 single-parameter, no-output-schema tool, the description covers purpose, needed input, expected return content, cost-relevant steps, and run blockers. It only lacks explicit usage direction and side-effect clarification.

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 schema already documents agent_id as 'From list_agents,' and the description adds the context that these are values needed for run_agent. That is helpful but not substantial; with 100% schema coverage the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource ('one agent') and the specific behavior ('what it does, step by step, and what it needs'), with concrete output categories. It is clearly distinct from siblings like list_agents (all agents) and run_agent (executes the agent).

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 a pre-run inspection use case by mentioning 'the values you must pass to run_agent' and blockers, but it never explicitly says when to prefer describe_agent over list_agents or run_agent. No alternatives or exclusions are 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?

With no annotations, the description carries the disclosure burden. It clearly says results include evidence for each candidate and warns that wrong suggestions can be recognized rather than blindly trusted. This goes beyond the schema and gives agents a useful expectation of output quality and intent.

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 no filler. The core purpose is front-loaded, and the second sentence adds return-value context that helps the agent interpret results. Every phrase 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 has only two simple parameters and no output schema, so the description covers the essential contract: what gets discovered, from which signals, and that candidates come with evidence. It could say a bit more about what evidence looks like, but it is sufficient for safe invocation.

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%: the keywords parameter is described there and in the tool description, but the domain parameter is only implied by 'this one'. The phrase 'sharpens the search half' adds meaningful context for keywords, but the main domain parameter still relies on inference from the tool name.

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 ('Find') and a clear resource ('domains competing with this one'), and it specifies the two methods used ('search results and link profile overlap'). This distinguishes competitor discovery from sibling tools like find_prospects or backlink_gap without needing to inspect schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool by framing it around competitor overlap and evidence, but it does not explicitly state when not to use it or name alternatives. A note that this is for competitor discovery rather than prospecting, qualification, or gap analysis would improve 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?

With no annotations provided, the description carries the full burden and does well: it discloses that the tool returns the subject and body, performs no sending, and that sending happens later from the user's mailbox. This is important behavioral context that an agent needs before invoking the 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, purposeful sentences: the action comes first, then the output and non-sending behavior, then the requirement. Every sentence earns its place and the structure is front-loaded.

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?

Since there is no output schema, the description correctly explains the return value (subject and body) and the non-sending behavior. It leaves 'page_title' and 'sender_name' semantically unexplained, but those are optional and the core invocation path is well-covered by the description and required parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, so the schema already documents most parameters. The description reinforces the meaning of 'hook' as the reason the prospect would link and 'prospect_url' as the target page, but it adds no new meaning for the undocumented optional params 'page_title' and 'sender_name'. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Write') and clearly identifies the resource and result: one outreach email for one prospect, returned as subject and body. It is clearly distinguishable from sibling discovery and verification tools, despite not naming them 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?

The description gives clear context: use this when you need to draft a single outreach email with a personalized reason. It also provides an important exclusion ('sends nothing') and a prerequisite ('paid Mentionry plan'), which helps the agent decide when and whether to invoke 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?

With no annotations, the description carries the behavioral burden. It discloses that the tool searches the open web and returns each kept result with a reason, which is useful. However, it does not mention result limits, latency, data-source caveats, or how the plausibility filtering works.

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

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

The description is two sentences with no filler. The core action and result format are front-loaded, and every phrase contributes meaning: what it searches, what types of pages it targets, and what it returns.

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 has five parameters, no annotations, and no output schema, but the description only covers the general purpose and one output behavior. Optional parameter semantics and usage boundaries versus sibling tools are missing, making the definition incomplete for confident invocation beyond the required domain.

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 40%, and the description does little to compensate for the undocumented parameters. 'domain' maps to 'this site' and 'subject' loosely relates to topic/audience/keywords, but audience, keywords, and description are not explained at all, leaving their semantics unclear.

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: 'Search the open web for pages that would plausibly link to this site.' It further specifies the types of pages (resource pages, roundups, listicles, directories), which clearly differentiates it from siblings like discover_competitors or backlink_gap.

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 intended use is implied: use this when you want link-building prospects for a given site. However, there is no explicit when-to-use or when-not-to-use guidance, and no alternative sibling tools are mentioned, so the agent must infer the selection 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 must carry the behavioral load, and it does disclose meaningful traits: the output is a public address, the result is attached to this tool's row, and the call consumes one image allowance with 'best' costing roughly 5x. It omits auth/permission requirements and whether the asset persists or can be regenerated/replaced.

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, front-loaded with purpose and followed by output/downstream behavior and cost. Every sentence carries information, though the semicolon-heavy middle sentence packs return value, consumers, and UI placement together, which is slightly heavy for one breath.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by explaining the returned public address and how it is consumed downstream, plus the allowance cost. For a 3-parameter tool with full schema coverage this is sufficient, with only persistence/auth details 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema by quantifying the cost of quality='best' and constraining its use. Aspect ratio meaning is already well covered in the schema, so the marginal gain is moderate rather than large.

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 concrete verb+resource ('Make one picture from a description') and enumerates representative outputs (product shot, social visual, hero art, ad creative). The word 'picture' plus the aspect-ratio examples cleanly separate it from the sibling generate_video.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear condition for the expensive path ('quality best ... use it only when asked') and names the downstream consumers (write_landing_page, write_email_template), which tells the agent when the result is worth generating. It never states when NOT to use this tool or when to prefer generate_video/an alternative.

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 does so richly: cost ('one video allowance, the dearest single action'), latency ('renders in one to two minutes'), output ('returns its public address'), UI behavior ('the product plays it under this tool's row'), and an account gate (paid plan). This is far beyond a bare restatement of the schema.

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

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

Front-loaded with the core action and outcome before cost and prerequisites, with no filler sentences. It is dense and packs several facts into each sentence, which borders on crowded but every clause carries operational value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers cost, latency, resolution trade-off, output (returns a public address), account requirement, and pre-call confirmation. With no output schema present, the description supplies the return behavior an agent needs, leaving no material gap for a 5-parameter 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 100%, so the baseline is 3, but the description adds real meaning on top: it ties quality 'best' to 720p 'at several times the cost' and connects first_frame_url to the output address of generate_image. It also frames the prompt as motion/scene content, though it doesn't add per-parameter syntax the schema lacks.

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 ('Make one short clip ... from a description') and bounds output immediately (three to eight seconds, 480p/720p). It explicitly distinguishes itself from the sibling generate_image by describing how to feed that tool's output in via first_frame_url.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear when-to-use context (generate a clip from a description, optionally animating an existing picture) and names the alternative source (a picture generate_image already made). It adds a concrete precondition ('confirm the description with the customer before calling it') and a hard gate ('Requires a paid Mentionry plan').

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 provided, the description carries the full burden of disclosing behavior. It does explain what the response includes, especially the useful 'whether it would run as it stands' readiness indicator. However, it does not explicitly state that the operation is read-only, nor does it mention permissions, rate limits, or response shape beyond field names.

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

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

The description is two sentences with no filler. The first sentence front-loads the tool's purpose and output fields, and the second sentence adds a concise, actionable next step. Every word 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 list operation, the description covers the key returned fields and suggests the next logical call. It is sufficient for an agent to invoke the tool correctly, though it omits potential details like ordering, pagination, or exact output schema, which would matter if the response were complex.

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 no parameters, so there is nothing to document. The baseline of 4 applies because the description does not need to compensate for missing parameter guidance.

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 that the tool lists agents on the account and enumerates the returned attributes: name, step count, runnability, and last modification time. It is distinguishable from describe_agent by positioning that as a follow-up, but it does not explicitly contrast with other list tools such as list_connections or list_documents.

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 a concrete usage flow: call list_agents to get an overview, then call describe_agent to learn requirements before running an agent. It implies this tool is for surveying agents and checking run-readiness, though it does not state explicit exclusions or alternatives like run_agent.

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 behavioral disclosure burden. It explains what the tool returns—connected external integrations and their allowed permissions—and implies a non-mutating lookup. It does not explicitly state read-only behavior, but nothing about the description suggests side effects.

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

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

Two sentences carry the full message: what the tool does and when to call it. The core purpose is front-loaded, 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 parameterless list tool with no output schema, the description sufficiently explains what the tool returns and when it should be used. It does not specify the exact response shape, but the agent knows 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?

The tool has zero parameters, so the baseline for parameter semantics is 4. The description adds no parameter-related confusion, and the schema already documents the empty input contract.

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 identifies the resource ('outside tools this account has connected') and the implied listing/read action. The phrase 'outside tools' distinguishes it from sibling tools like list_agents and list_documents.

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 an explicit trigger: call before offering to file, post, or draft anything, so the agent can report what is actually available. It does not mention alternatives or when-not-to-use cases, so it stops just short of a 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?

With no annotations, the description carries full behavioral disclosure. It states that the tool returns metadata only and not text, and that ids are meant for read_document. However, it leaves 'how long it is' ambiguous (characters, words, pages?) and says nothing about pagination, ordering, or limits, which is a noticeable gap for an unannotated 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?

Two sentences with no filler: the first states the main purpose with specific output fields, and the second provides a useful routing hint. The most important information is front-loaded, and every sentence contributes value.

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 list tool without an output schema, the description covers the essential output fields and points to read_document for content retrieval. Minor omissions exist, such as the exact definition of 'length' and any list ordering/limits, but the tool is simple enough that an agent can 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?

The input schema has zero parameters and schema description coverage is effectively 100%, so there is no parameter documentation burden. The description adds no parameter-specific info, but it clarifies the output id's role with read_document. The no-parameters case warrants the baseline score of 4.

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 ('list') and a clear resource ('documents your agents have produced') and enumerates the returned fields: name, author agent, length, and version count. It also differentiates from read_document by noting that text requires a separate call, making the tool's role unambiguous among its siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly routes text retrieval to read_document ('Pass an id to read_document for the text'), which tells the agent when not to use this tool. It implies the tool is for metadata overviews, though it doesn't explicitly state 'use this when you need document metadata.' The context is clear and actionable.

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 useful traits beyond schema: result ordering ('newest first'), that items carry addresses, and that the call is 'Free.' It omits pagination, result limits, and any auth/scope requirements, which matters for a list endpoint.

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 terse sentences, zero filler, with scope and ordering front-loaded and the cost note tacked on at the end. Every fragment 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 list tool with no annotations and no output schema, the description adequately conveys what is returned (pictures and clips with their addresses) and in what order. The only meaningful gap is absent pagination/limit behavior, which is a minor omission at this complexity level.

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. The description adds no parameter details because none exist, and schema description coverage is reported at 100%; nothing further is required 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?

The description names a specific resource and scope ('pictures and clips already generated on this account'), which clearly separates it from generate_image/generate_video (creation) and from list_documents/list_agents (other resource types). The listing verb is only implied by the title rather than stated in the description, so it falls just short of a clean verb+resource statement.

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 – an agent can reasonably infer you call this to enumerate previously generated media – and 'Free.' hints at a cost condition. However, there is no explicit when-to-use/when-not guidance and no comparison to any alternative retrieval path.

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 burden of behavioral disclosure. It states that the tool uses live search data, returns a verdict with measured signals and the honest case against, and is the same free diagnostic as the dashboard. This gives a clear picture of the tool's behavior and output without relying on structured metadata.

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

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

Three sentences, each earning its place: the first states the core purpose, the second describes the output, and the third provides useful expectation-setting. No redundant or filler language is present.

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 diagnostic tool with no output schema, the description is complete. It covers the purpose, data source, output shape, and the likely outcome, giving an agent enough context to invoke the tool appropriately and interpret its 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 input schema already fully documents the single parameter with a descriptive example ('mentionry.com'), so schema coverage is 100%. The description adds no additional parameter-level meaning, which keeps this at the baseline of 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: 'Judge whether a domain is worth running link building for at all'. It clearly distinguishes the tool from sibling tools like find_prospects or backlink_gap by focusing on the qualification verdict rather than prospect discovery or gap analysis.

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 clearly frames when to use the tool—before investing in link building for a domain—and sets expectations by noting that many sites will not be worth pursuing. It does not explicitly name alternative sibling tools or state when not to use it, 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?

With no annotations, the description carries the full burden. It discloses version resolution ('Returns the newest version unless an older one is asked for') and the returned payload components. It does not mention failure modes or permissions, but for a read operation this is a minor gap.

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 front-load the core purpose and then add the version detail. Every clause contributes meaningful information with no redundant 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 simple read tool with no output schema, the description sufficiently covers the returned content and versioning, and the schema fully documents parameters. Minor omissions such as not-found behavior keep it just short of complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so document_id and version are already explained. The description mostly restates the version behavior already in the schema and adds no significant new parameter-level meaning.

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 identifies the resource ('one document your agent wrote'), the kind of output (text plus agent, step, and values), and the version behavior. This differentiates it from siblings like list_documents and read_site.

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 explicit: an agent can infer this is for retrieving document content, but no alternatives or when-not-to-use conditions are named. There is no guidance distinguishing it from list_documents or other document-related 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?

With no annotations, the description carries the burden. It discloses that the result is an interpretation ('what we think it is about'), implicitly signals a read-only operation via 'Read', and specifies the returned components. It could add caveats about freshness or edge cases, but it is reasonably transparent for a simple read 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?

Two sentences, front-loaded with purpose and output, followed by usage guidance. Every sentence adds value and there is no redundant 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 single-parameter tool with no output schema, the description covers the output shape, the read intent, and the workflow position. The main gap is parameter format guidance, but the overall context is sufficient for an agent to invoke the tool reasonably.

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 0%, so the description must compensate. It only restates the concept of 'domain' without specifying format, examples, or whether to include protocol/subdomains. The property name 'domain' already conveys the basic meaning, so the description adds little 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 states a specific action ('Read a domain') and defines the deliverable: a description, audience, and target keywords. It also frames this as the foundational brief for sibling tools, which distinguishes it from tools like qualify_domain or read_document.

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 an explicit when-to-use directive: 'call it first when you do not already have one.' This clearly tells an agent the tool produces the shared input needed by other tools, making the intended workflow unmistakable.

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 provided, the description carries the full burden of behavioral disclosure. It does well by framing the operation as reading 'recorded answers' and returning measurements, which implies a read-only, side-effect-free operation. It also discloses what the grouping options produce (trend versus bucket comparisons), exceeding the minimal safety disclosure expected.

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

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

Three sentences, each earning its place: the first lists the metrics, the second explains grouping choices, and the third gives dashboard context. The description is front-loaded with the core function and contains 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 read tool with no output schema, the description explains the return concept well by naming the metrics and grouping behavior. It doesn't specify the exact response shape or edge cases, but with simple parameters and no nested objects, that is a minor 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 description coverage is 100%, so the baseline is 3. The description adds meaning by tying the dimension parameter to analytical intent ('find where a brand is weak') and explicitly mapping day to trend and the other dimensions to comparisons, going slightly beyond the schema's terse enum descriptions.

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 'read' and resource 'visibility' while enumerating exact metrics: visibility, share of voice, mean position, and competitor ranking. It clearly distinguishes this tool from sibling tools like read_document and discover_competitors by focusing on the account's own answer-engine measurements.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context by stating this is 'the data behind the dashboard's Answer Engine Insights' and gives explicit guidance on when to use each grouping: day for trends, and model/region/persona/prompt/topic for finding weak spots. It doesn't name when-not-to-use alternatives, but the context is strong and the sibling list shows no overlapping analytics 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?

With no annotations, the description carries the full burden of behavioral disclosure. It does well by explaining the sequence and content of the return value ('what every step did, in order, with what it returned and how long it took') and by disclosing that paid-vendor steps consume allowance. It could mention potential real-world side effects of running an agent, but the provided details are substantial beyond the bare schema.

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

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

Three dense sentences, each earning its place: the first defines the behavior and output, the second tells the agent how to structure invocation, and the third discloses the cost implication. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with no output schema, the description covers the high-level return shape, the input construction method, and a key consumer warning. It is almost complete, but lacks an explicit statement of what happens on failure or whether the run is synchronous, which 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics for the inputs parameter by stating it must be an object keyed by the `key` values from describe_agent, which goes beyond the schema's generic 'keyed by key'. It does not add much about agent_id, but the schema already covers it with 'From list_agents.'

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Run', the resource 'one of your agents', and the singular execution mode 'once'. It is immediately distinct from siblings like describe_agent, list_agents, and draft_pitch because it describes executing an agent and reporting the step-by-step results.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a concrete usage pointer: pass inputs keyed by their `key` from describe_agent, implying that describe_agent should be consulted first. It also flags a cost-related condition for paid vendor steps. It does not explicitly list when not to use the tool or name an alternative, but the execution purpose is clear enough in 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 provided, the description carries the full behavioral burden. It explains the live-profile check, the reported fields, and the important nuance that removed links appear as changes rather than remaining on the scoreboard. It does not cover errors, rate limits, or propagation delays, but the core behavior is clearly disclosed.

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 dense sentences with no filler. The main action and output are front-loaded, and the second sentence adds a valuable behavioral detail that prevents misinterpretation of removed links.

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 tool with only two simple parameters and no output schema, the description provides everything an agent needs to invoke it correctly: what to supply, what the report contains, and how removed links are treated. No critical behavioral information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are already fully documented. The description adds only marginal parameter-level context by framing 'pitched' as the domains to check and 'domain' as your own domain, which mostly restates the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Check a list of domains against your live backlink profile') and clearly defines the output: which domains now link, when the link first appeared, and whether it is still present. It distinguishes itself from backlink-related siblings like backlink_gap by focusing on verifying previously pitched domains rather than finding gaps or prospects.

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 clearly implies its context: verifying whether pitched domains have landed links in the live backlink profile. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of the highest tier of usage 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 burden and does reasonably well: it discloses the cost ('Spends one draft allowance'), the persistence side effect (filed in Documents), and the grounding dependency on a brand kit. It omits permission/auth requirements and what happens if the draft allowance is exhausted, which keeps it from a 5.

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

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

Three front-loaded sentences that each carry information: what is produced, how it is grounded, and where the result can go. No filler, though the clause about Outlook/Gmail rendering is parenthetical detail that could be trimmed.

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 11-parameter generative tool with no annotations and no output schema, the description covers the output artifact and cost but says almost nothing about the inputs, so the agent cannot tell what a good 'brief' looks like or how sections/cta fields map to the rendered email. Adequate minimum viability, but with a clear parameter-semantics 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 description coverage is only 18% (just title and images), and the description does not compensate by explaining the other nine parameters (goal, tone, notes, offer, audience, sections, cta_url, cta_text, preheader). 'From a brief' is the only hint at how the inputs are consumed, leaving the agent to infer the meaning and format of most fields.

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+resource (write an HTML marketing email) and specifies the technical rendering approach (tables and inline styles for Outlook/Gmail) plus the side effect (filed in Documents for preview). It is clearly distinguishable from siblings like write_landing_page and create_email_draft, which is explicitly framed as a downstream destination rather than the same action.

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 the grounding condition ('when a brand kit exists') and routes the agent to the correct downstream tools, noting that create_email_draft and app actions 'ask first'. It never states when NOT to use this tool (e.g., plain-text or non-marketing emails), so it stops short of full when/when-not coverage.

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 does real work: it discloses the output format and destination, that the draft is private until publish_page, that it draws on the brand kit, and that it spends one draft allowance (a quota/cost signal). It omits permission requirements, overwrite behavior on title collision, and failure modes, so it falls short of fully transparent.

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 action is front-loaded and each sentence adds distinct information (output, brand grounding, image inputs, privacy/quota). Minor looseness in clauses like 'where the customer previews it' keeps it from being maximally tight.

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 10-parameter mutation tool with no annotations and no output schema, the description covers output, privacy, quota, brand grounding, and image inputs, but leaves several parameters (offer, tone, cta_url, cta_text, audience) with no meaning anywhere and does not explain what 'starts from a brief' means relative to the title/goal fields.

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%: goal, notes, title, images, and sections are documented in the schema, while tone, offer, cta_url, cta_text, and audience are undocumented in both places. The description reinforces the images parameter's provenance ('/m/... addresses from generate_image') and the notion of a brief, but does not compensate for the unexplained CTA and audience fields.

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 (write) and resource (a complete, responsive landing page as HTML) with the destination (Documents) and the previewing party named. An agent can distinguish this from content-producing siblings like write_email_template or draft_pitch solely from the description.

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?

Conditional guidance is present: 'Grounded in the brand kit when one exists' and 'Pass the addresses of pictures you generated so the page uses them' tell the agent when certain inputs apply. It also routes the publish step to the sibling publish_page. However it does not state when this tool is preferred over other authoring tools or what preconditions must hold to call it.

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