pSEO Engine

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 so thoroughly: it discloses asynchronous behavior, the cost, the return of a jobId, the polling mechanism, the scope ('all generated pages'), and the non-mutating 'reports only' behavior. This gives the agent an accurate operational model before calling.

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 pack essential operational details while staying readable. The ASYNCHRONOUS warning is front-loaded, followed by scope, cost, return type, polling instruction, and an important limitation. No sentences are wasted.

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

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

For a one-parameter async tool with no output schema and no annotations, the description covers everything needed to invoke and follow up correctly: what it scans, what it reports, what it costs, what it returns, and how to retrieve results. The absence of an output schema is mitigated by the explicit pointer to seo.job.status.

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

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

Schema description coverage is 100%, and the schema itself already explains that projectId must be the exact cuid from seo.project.list rather than a slug or display name. The description adds little about the parameter, but the schema is strong enough that no additional compensation is 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?

The description states a specific behavior: scanning all generated pages for broken text, unfilled placeholders, truncated copy, and missing images, recording findings per page. It also distinguishes itself from any fix-oriented operation by explicitly stating that it only reports problems and does not fix 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?

The description clearly tells the agent this is asynchronous, should be followed by polling seo.job.status, and is for reporting rather than fixing. It also embeds a prerequisite in the parameter description: call seo.project.list first if no projectId is available. It does not name an alternative audit tool, but none is needed among the siblings.

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 zero annotations, the description carries the full burden and does an excellent job: it flags ASYNCHRONOUS, states the financial cost (25c plus per-page), relies on project configuration, and discloses the state transition (GENERATED, not live). This goes well beyond what the schema conveys.

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 a single, dense sentence group that front-loads the critical flag (ASYNCHRONOUS) and then layers the prerequisite, side effect, and follow-up action without a single wasteful phrase. Each sentence carries necessary 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?

Although there is no output schema, the description explains exactly what is returned (jobId), how to proceed (poll seo.job.status), and what the result state is before publishing. Paired with 100% schema coverage, this is complete for an async tool with a single parameter.

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

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

Schema description coverage is 100%, so the schema already documents projectId fully. The description adds no additional parameter meaning beyond reinforcing that it refers to the whole project and all pending rows, which is minor. Baseline 3 is appropriate.

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

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

States a specific verb ('starts'), resource ('content-generation queue'), and scope ('every PENDING row'), which clearly distinguishes it from sibling tools like seo.audit.start and seo.research.start. The status outcome ('GENERATED... NOT live') further pins down the purpose.

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

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

Explicitly tells when to call it: after verifying readyToGenerate via seo.project.get. Also directs the subsequent flow by telling the agent to poll seo.job.status and to not treat generated pages as live until approved and published. No similar guidance is needed for siblings.

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 does the full work of disclosing behavior: it says the call is free, implies it is a non-mutating polling operation by calling it a status check, and warns about interaction with sibling start tools. It does not specify the empty/no-job case or authentication requirements, but it is far more transparent than a simple 'returns status' statement.

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

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

The description is three sentences, each with a distinct purpose: function/output, usage and polling cadence, and restriction. It is front-loaded with the return information. It could be more compact, but there is no waste, and every sentence adds necessary context.

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 status polling tool with no output schema, the description covers the return fields, the polling cadence, the free cost, and a critical disallowed situation. Missing only the empty/no-job return and any authentication note, but these are not essential for an agent to be able to use the tool correctly in context.

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 is fully described at 100% coverage, including projectId format, an example, and guidance to call seo.project.list if lacking one. The description adds nothing about the parameter beyond identifying 'a project', so the baseline 3 is appropriate because the schema already carries that burden.

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 action ('Returns'), the resource ('the most recent background job for a project'), and the specific output contents (type, status, progress counters, last log line). It also establishes itself as a polling/status tool distinct from the sibling start tools by framing the return value as the status of a job that other tools initiate.

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 explicitly directs when to call: 'poll this every few seconds after any tool that starts a job.' It also provides a clear prohibition and consequence: 'Do NOT re-call the start tool while status is RUNNING; it will be refused.' This gives an agent complete conditional context for invoking both this tool and its sibling start tools.

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

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

No annotations are provided, so the description carries the burden. It discloses that the project is created EMPTY and needs more setup before seo.content.generate works, and mentions returns projectId, but doesn't detail permission requirements, error conditions, or reversibility of creation. For a creation tool with no annotations, this is a moderate gap but still adds useful behavioral context beyond a simple 'creates' statement.

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 with high information density. The most actionable context (when to call, what it returns) is front-loaded, and the follow-up instructions are concise. No wasted words.

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

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

Given the tool has a clear purpose, an output schema is absent but the description covers the return value, the empty-state caveat, and the required subsequent step. With three well-documented parameters, the description fills all critical gaps an agent needs to call 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?

Schema coverage is 100%, so all three parameters are already described in the schema. The description doesn't add significant meaning beyond the schema; it mentions 'name' indirectly via the example but adds no syntax or format details for 'domain' or 'template' that aren't already in the schema. Baseline 3 is appropriate as schema carries the heavy lifting.

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 ('Creates'), the resource ('programmatic-SEO project'), and a key output ('returns its projectId'). It also distinguishes the tool from siblings by naming seo.project.list and noting the dependency chain, which prevents confusion with other project-related 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?

Explicitly tells the agent when to use it: 'Call this when seo.project.list comes back empty'. It also explains why (all other tools need a projectId) and what to do afterwards (call seo.project.get and read readinessNote), providing clear decision 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?

No annotations are present, so the description must carry the burden. It says 'Returns' which implies a non-destructive retrieval, but it doesn't explicitly state that it has no other side effects, doesn't mention authentication requirements, and doesn't describe rate limits or other costs beyond 'FREE'. The 'FREE' and prerequisite conditions add context but leave some behavioral traits unspoken.

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 short sentences, each contributing useful information: what is returned, the cost, and the recommended usage. The main purpose is front-loaded, and there is no redundancy or filler content.

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 one-parameter tool with no output schema, the description provides enough high-level context: that it returns config and readiness, what that readiness means, and how/when to use it. Output field details (e.g., exact structure of settings) are absent, but for a single-param GET tool this is not a critical miss; a bit more detail on the expected response shape would make it fully complete.

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

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

Schema coverage is 100% – the single parameter projectId has a thorough description including how to obtain it, format, and examples. The description text itself adds nothing more about the parameter, so the baseline of 3 is appropriate since the schema does all the work.

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 ('Returns') and exact resource ('one project's settings'), plus the readiness condition ('configured enough to generate content'), which is unique and distinguishable. Mentions the sibling seo.content.generate directly, making the role of this tool clear relative to 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?

Explicitly instructs to 'Use this before seo.content.generate', names the alternative, and explains the benefit ('avoid starting a run that will immediately fail'). The FREE indicator adds incidental guidance. This is exactly the when-to-use vs. alternative guidance requested.

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. It discloses the scope ('this API key can act on'), the FREE cost implication, and the critical constraint that ids cannot be guessed or carried over. It doesn't mention pagination or rate limits, but for a zero-parameter list call the disclosed behavior is quite useful.

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: what it returns, the cost note, and the critical usage ordering. The most important operational guidance ('Call this FIRST') is front-loaded in the second sentence and the rationale is 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 zero-parameter, no-output-schema tool, the description is nearly complete: it names the resource, the returned fields, the cost, and the session-ordering requirement. It could add pagination or sorting behavior, but nothing an agent needs to invoke it correctly is missing.

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

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

There are zero parameters, so the schema provides no semantics to add. The description compensates by explaining what the returned list contains (id, name, slug, custom domain, page count), which is the relevant semantic context for a parameterless call. Baseline 4 for zero params 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 verb ('Lists') and resource ('every programmatic-SEO project this API key can act on'), and enumerates the returned fields (id, name, slug, custom domain, page count). It clearly distinguishes this from siblings like seo.project.get and seo.project.create by focusing on listing all accessible projects.

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

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

The description explicitly says to call this FIRST in any session and explains why: every other tool needs a projectId from here, and ids cannot be guessed or carried over from another account. This is strong when-to-use guidance that also implies when not to use alternatives (e.g., seo.project.get for a single known project).

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?

While there are no annotations to contradict, the description goes beyond basics: it discloses the synchronous nature, the cost (5c), and the critical behavioral nuance that GENERATED drafts are skipped. It also explains how to interpret the response (publishedCount and skippedNeedsReview), which is valuable for an agent to avoid confusion.

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 dense but every sentence adds value: synchronous flag, cost, status rule, and response interpretation. The only minor issue is that 'SYNCHRONOUS' and cost are somewhat technical and could be front-loaded better, but the most important behavioral rule (status filter) is placed prominently.

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

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

Given the tool is a single-parameter publish action, the description covers the essential operational details: what happens, what's skipped, how to interpret results, and cost. The lack of an output schema is compensated by describing the response fields. There's no ambiguity left for an agent to guess about.

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 covers projectId fully with type, format example, and instruction to use exact id. The description reinforces by restating the need for the exact project id and when to fetch it, adding a conditional workflow hint that goes beyond the schema. Since schema coverage is 100%, this is above baseline.

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

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

Clearly states the verb and resource ('Takes approved pages live') and distinguishes itself from siblings by explaining it publishes approved pages, not generating or auditing. It also clarifies the scope ('only rows in REVIEWED status'), which sets it apart from content generation or listing 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?

Explicitly tells the agent when to use it (when pages are approved) and when not to (when pages are in GENERATED draft status), with a clear reason (human approval gate). It even instructs to call seo.project.list first if no projectId, which is actionable 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?

Without annotations, the description clearly discloses the asynchronous nature (returns immediately with jobId, keywords not yet created), the cost (50c and AI spend), and the failure condition (if a run is in progress). This goes beyond what annotations would provide, giving critical behavioral transparency.

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

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

Three sentences, front-loaded with the most important info (async and cost), no filler. Each sentence adds essential usage information, making it efficient and scannable.

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 start-operation with no output schema, the description covers all necessary aspects: how to call, what to expect (jobId), what to do next (poll), and the limitations. Complete given the tool's simplicity.

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?

Even though the schema provides 100% coverage, the description adds value: it clarifies the 'brief' parameter's need for client context, reinforces the projectId format and warns against using slug or display name, and gives a starting point for targetCount (200). This enhances the schema information.

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

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

The description clearly states the tool's purpose: starting an asynchronous keyword-research run that mines keywords into pending rows. It uses specific verbs ('starts', 'mines', 'qualifies') and a definite resource ('keyword-research run'), distinguishing it from siblings like seo.audit.start and seo.content.generate.

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

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

Explicit usage guidance is provided: call it once, poll seo.job.status until completed, and it fails if a run is already in progress. It also mentions cost implications, encouraging minimal calls. This clearly signals when to use and when not to use, and points to the polling 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?

No annotations exist, so the description carries the burden. It adds valuable behavioral details: cost per call, explicit exclusion of content bodies, and a full status enum with human-readable meanings. It does not mention pagination semantics, but the provided details go beyond a bare function summary.

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 tight sentences, front-loaded with the core action, then cost, then status semantics. Every clause adds useful information without fluff 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 list operation, the description covers purpose, cost, filter dimension, and critical limitation (no bodies). It doesn't mention pagination tokens or ordering, but the presence of 'a page of rows' and limit parameter partially covers this. Solid overall coverage.

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 documents limit, status, and projectId thoroughly. The description adds little to parameter understanding beyond calling rows 'generated pages', but that context is minor. Baseline of 3 is appropriate since the schema covers semantics.

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 starts with a specific verb and resource ('Returns a page of rows... generated pages') and states key returned fields (slug, target keyword, status). This clearly differentiates it from sibling tools like seo.project.list, which lists projects rather than row-level page data.

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 explicit guidance on when to choose this tool over alternatives, nor any prerequisites (e.g., call seo.project.list first to get a project ID). The status list implies monitoring use cases but is not framed as a when-to-use instruction.

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